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Assert 


稳定 度 : 2 -稳定 

本 模块 被 用 来 为 你 的 应 用 编写 单元 测试 ， 你 可 以 通过 require('assert') 来 使 
用 它 。 

assert.fail(actual, expected, message, operator) 

抛 出 一 个 打印 实际 值 actual 和 期 望 值 expected 的 异常 ， 使 用 分 隔 

符 operator 隔 开 。 

assert(value[, message]), assert.ok(value[, message]) 
测试 value GAH» CRF assert.equal(true, !!value, 
message); ° 

assert.equal(actual, expected[, message]) 

判 等 actual 4 expected 是 否 相 等 ， 等 同 于 使 用 == 进行 比较 。 
assert.notEqual(actual, expected[, message]) 


判断 actual 4 expected 是 否 不 相等 ， 等 同 于 使 用 != 进行 比较 。 


assert.deepEqual(actual, expected[, message]) 

深度 判断 相等 ， 通 过 比较 actual 4 expected MARMA (prototype) 之 外 的 属 
性 是 否 相 等 〈 == ) 来 判断 二 者 是 和 否 相 等 。 
assert.notDeepEqual(actual, expected[, message]) 


深度 判断 不 相等 ， 与 assert.deepEqual 的 结果 相反 。 


assert.strictEqual(actual, expected[, message]) 


判断 actual 4 expected 是 否 “ 全 等 ( === ) ”。 


assert.notStrictEqual(actual, expected[, message]) 


判断 actual 4 expected 是 否 “ 不 全 等 ( !== ) ”。 


assert.deepStrictEqual(actual, expected[, message]) 


深度 判断 全 等 ， 通 过 比较 actual 与 expected MAMA (prototype) 之 外 的 属 
性 是 否 全 等 ( == ) 来 判断 二 者 是 否 相 等 。 


assert.notDeepStrictEqual(actual, expected[, message]) 


深度 判断 不 全 等 ， 与 assert.deepStrictEqual 结果 相反 。 


assert.throws(block[, error][, message]) 


JAY block 抛 出 一 个 error 。 error TRÆ AA’ EKAN” RAE h 
数 。 


使 用 构造 函数 验证 实例 : 


assert.throws( 
function() { 
throw new Error("Wrong value"); 


ty 


ERGO 


); 


使 用 正则 表达 式 验证 错误 信息 : 


assert.throws( 
function() { 
throw new Error("Wrong value"); 
ty 
/value/ 
); 


自 定 义 错 误 验 证 : 


assert. throws ( 
function() { 
throw new Error("Wrong value"); 


ty 


function(err) { 


if ( (err instanceof Error) && /value/.test(err) ) { 
retúrn true; 


} 
ty 


"unexpected error" 
); 
assert.doesNotThrow(block[, message]) 


MŽ block 不 抛 出 错误 ， 详 情 见 assert.throws ° 


assert.ifError(value) 


测试 value 是 否 为 假 ， 当 value 为 丨 时 会 抛 出 异常 。 通 常用 来 判断 回调 函数 中 
第 一 个 error 参数 。 


Buffer 


稳定 度 : 2 -稳定 


纯粹 的 JavaScript 是 Unicode 友 好 的 ， 但 是 不 能 很 好 地 处 理 二 进 制 数 据 。 当 处 理 
TCP 流 或 者 文件 流 时 ， 操 作 八 进 制 流 是 必要 的 。 node.js 提供 了 多 种 策略 来 操 
作 ， 创 建 和 使 用 八进制 流 。 


原始 的 数据 被 存储 在 Buffer 类 的 实例 中 ， 一 个 Buffer 类 似 于 一 个 整数 数组 但 
是 使 用 了 V8 扒 之 外 的 内 存 分 配 。 一 个 Buffer 不 能 被 改变 大 小 。 


Buffer 类 是 全 局 的 ， 所 以 它 是 少数 的 不 用 require('buffer') 就 能 使 用 的 对 象 


Buffer 和 JavaScript 字符 串 对 象 之 间 的 转换 需要 指定 一 个 明确 地 编码 方法 。 
以 下 是 一 些 不 同 的 字符 串 编码 。 


'ascii' - 仅 供 7 位 的 ASCII 数 据 使 用 ， 这 个 编码 方法 非常 的 快速 ， 而 且 会 剥离 过 高 的 
位 (如 果 有 设置 ) © 


'Utf8' - 多 字 节 编码 的 字符 。 许 多 web 页 面 和 一 些 其 他 文档 都 使 用 UTF-8 编 码 。 


'utf16le'- 2 或 4 个 字 节 ， little endian 编码 字符 。 支 持 (U+10000 到 
U+10FFFF) 的 代理 对 。 


'ucs2' - 'Utf16le' 的 别名 。 
'base64' - Base64 字符 串 编码 。 


'binary' - 一 种 通过 使 用 每 个 字符 的 前 八 位 来 将 二 进 制 数据 解码 为 字符 串 的 方式 。 这 
个 编码 方法 已 经 不 被 推荐 使 用 ， 在 处 理 Buffer WAN MHRA CE > Rh HAG 
会 在 node.js 的 未 来 版 本 中 移 除 。 


hex' - 把 每 个 字 节 编码 成 2 个 十 六 进 制 字符 。 
从 一 个 Buffer 创建 一 个 类 型 数组 (typed array) 遵 循 以 下 的 说 明 : 


1， Buffer 的 内 存 是 被 复制 的 ， 不 是 共享 的 。 


2° Buffer 的 内 存 被 解释 当做 一 个 数组 ， 而 不 是 一 个 字 节 数组 (byte array) ° KS 
Ž > new Uint32Array(new Buffer([1,2,3,4])) 创建 了 一 个 4 个 元 素 
([1,2,3,4]) 的 Uint32Array ,不 是 一 个 只 有 一 个 元 素 ([0x1020304] 或 
[0x4030201]) 的 Uint32Array ° 


注意 : Node.js v0.8 只 是 简单 得 在 array.buffer 中 保留 了 buffer 的 引用 ， 而 
不 是 复制 一 份 。 
Class: Buffer 


Buffer 类 是 一 个 全 局 类 用 于 直接 处 理 二 进 制 数据 。 它 的 实例 可 以 被 多 种 途径 构建 。 


new Buffer(size) 
e Size Number 
分 配 一 个 大 小 为 指定 size 的 八 位 字 节 的 新 buffer 。 注 意 ， size 不 能 超过 
kMaxLength， 否 则 一 个 RangeError 将 会 被 抛 出 。 
new Buffer(array) 
e array Array 


使 用 一 个 八进制 数组 分 配 一 个 新 的 buffer ° 


new Buffer(buffer) 
e buffer Buffer 


将 传递 的 buffer 复制 进 一 个 新 的 Buffer 实 例 。 


new Buffer(str[, encoding]) 


e str String - 传 入 buffer 的 字符 串 
e encoding String - 可 选 ， 使 用 的 编码 


根据 给 定 的 str 创建 一 个 新 的 buffer ， 编 码 默认 是 UTF-8 ° 


Class Method: Buffer.isEncoding(encoding) 


e encoding String 将 要 被 测试 的 编码 ， 返 回 true 若 此 编码 是 合法 的 ， 否 则 返 


回 false ° 


Class Method: Buffer.isBuffer(obj) 


e obj Object 
e Return: Boolean 


测试 obj <GA—* buffer ° 
Class Method: Buffer.byteLength(string[, encoding]) 


e string String 

e encoding String, TÆ > AA: "utf8' 

e Return: Number 
给 出 string 的 实际 字 节 长 度 。 编 码 默 认为 UTF-8。 这 
与 String.prototype.length 不 同 ， 因 为 String.prototype.length A% 
字符 囊 中 字符 的 数量 。 


例子: 


str = '\u00bd + \uOObc = \UdObe'; 


console.log(str + 1: " + str.length + 1 characters, " + 


Buffer.byteLength(str, 'utf8') + " bytes"); 


y mharartarc 19 huvuta 
ļ9menaracters, A DYtes 


Class Method: Buffer.concat(list[, totalLength]) 


e list Array 需要 被 连接 的 Buffer 对 象 
e totalLength Number 将 要 被 连接 的 buffers 的 
e Returns 连接 完毕 的 buffer 


list 为 空 ， 或 为 0， 那 么 将 返回 一 个 长 度 为 0 的 buffer。 
list 只 有 一 个 元 素 ， 那 么 这 个 元 素 将 被 返回 。 若 list 有 超过 一 个 元 素 ， 那 
么 将 创建 一 个 新 的 Buffer 实 例 。 如 果 totalLength 没有 被 提供 ， 那 么 将 会 


ak 
7a 
ak 


从 list 中 计算 读 取 。 但 是 ， 这 增加 了 部 数 的 一 个 额外 的 循环 ， 所 以 如 果 直 接 长 度 


那么 性 能 会 更 好 。 


Class Method: Buffer.compare(buf1, buf2) 


e buf1 Buffer 
e buf2 Buffer 与 buf1.compare(buf2) 相 同 . 对 于 排序 一 个 Buffers 的 数组 非常 有 用 : 


var arr = [Buffer('1234'), Buffer('0123')]; 
arr.sort(Buffer.compare) ; 


buf.length 


e Return Number 这 个 buffer 的 字 节 长 度 。 注 意 这 不 一 定 是 这 个 buffer 中 的 内 容 长 
度 。 它 是 这 个 buffer 对 象 所 分 配 内 存 大 小 ， 并 不 会 随 着 buffer 的 内 容 的 改变 而 改 


buf = new Buffer(1234); 


console.log(buf.length); 
buf.write("some string", ©, "ascii"); 
console.log(buf.length); 


( [e234 


/ 1234 


虽然 buffer 的 length 属性 并 不 是 不 可 变 的 ， 改 变 length 属性 的 值 可 能 会 使 
之 变 成 undefined 或 引起 一 些 不 一 致 的 行为 。 和 希望 去 改变 buffer 的 length 的 
应 用 应 当 把 它 视 作 一 个 只 读 的 值 ， 并 且 使 用 buf.slice 来 创建 一 个 新 

的 buffer 。 


buf = new Buffer(10); 
buf.write("abcdefghj", 0, "ascii"); 
console.log(buf.length); // 10 

buf = buf.slice(0,5); 
console.log(buf.length); // 5 


buf.write(string[, offset][, length][, encoding]) 


e string String 准备 被 写 入 buffer 的 数据 
e offset Number 可 选 ， 默 认为 0 


e length Number 7% > RUA buffer.length - offset 
e encoding String T& > RUA 'utf8' 


从 指定 的 偏 移 位 置 (offset) 使 用 给 定 的 编码 向 buffer 中 写 入 字符 串 ， 偏 移 位 置 默认 为 
0， 编 码 默 认为 UTF8。 长 度 为 将 要 写 入 的 字符 串 的 字 节 大 小 。 返 回 被 写 入 的 八进制 
流 的 大 小 。 如 果 buffer 没 有 足够 的 空间 写 入 整个 字符 串 ， 那 么 它 将 只 会 写 入 一 部 
分 。 length 参数 默认 为 buffer.length - offset ， 这 个 方法 将 不 会 只 写 入 字 
符 的 一 部 分 。 


buf = new Buffer(256); 
len = buf.write('\uQ0bd + Xu0gbc = \u00be', 0); 
console.log(len + " bytes: " + buf.toString('utf8', ©, len)); 


buf.writeUIntLE(value, offset, byteLength[, noAssert]) 
buf.writeUIntBE(value, offset, byteLength[, noAssert]) 
buf.writelntLE(value, offset, byteLength[, noAssert]) 


buf.writelntBE(value, offset, byteLength[, noAssert]) 


e value {Number} 将 要 被 写 入 buffer 的 字 节 

e offset {Number} © <= offset <= buf.length 
e byteLength {Number} 0 < byteLength <= 6 
e noAssert {Boolean} 默认 为 false 

e Return: {Number} 


根据 指定 的 偏 移 位 置 (offset) 和 byteLength 将 value 写 入 buffer。 最 高 支持 48 位 
的 精确 度 。 例 子 : 


var b = new Buffer(6); 


b.writeUIntBE(0x1234567890ab, 0, 6); 


DU 516 78 90 ab 


将 noAssert 设置 为 true 将 会 跳 过 value 和 offset 的 检验 ， 默 认为 false 。 


buf.readUIntLE(offset, byteLength[, noAssert]) 


buf.readUIntBE(offset, byteLength[, noAssert]) 
buf.readintLE(offset, byteLength[, noAssert]) 


buf.readintBE(offset, byteLength[, noAssert]) 


e offset {Number} © <= offset <= buf.length 
e byteLength {Number} 0 < byteLength <= 6 
e noAssert {Boolean} 默认 为 false 

e Return: {Number} 


x2 
加 


一 个 普遍 的 用 来 作 数值 读 取 的 方法 ， 最 高 支持 48 位 的 精确 度 。 例 子 : 


var b = new Buffer(6); 
b.writeUint16LE(0x90ab, 0); 
b.writeUInt32LE(0x12345678, 2); 
b.readUIntLE(0, 6).toString(16); 


output: '1234567890ab 


将 noAssert 设置 为 true 将 会 跳 过 value 和 offset 的 检验 ， 这 意味 
A offset 将 可 能 超过 buffer 的 结束 位 置 ， 默 认为 false 。 


buf.toString([encoding][, start][, end]) 


e encoding String, 可 选 ， 黑 认为 "utf8' 
e start Number, T& > RUA 0 
e end Number, 可 选 默认 为 ”buffer,length 


从 编码 的 buffer 数 据 中 使 用 指定 的 编码 解码 并 返回 结果 字符 串 。 如 
Æ encoding A undefined 或 null ， 那 么 encoding 将 默认 为 
UTF8° start 和 end 参数 默认 为 0 和 buffer.length ° 


buf = new Buffer(26); 
for (var i= 0 >; i <= 26 ; a+) ¢ 
buf[i] = i + 97; 77 97 is ASCII a 
} 
buf.toString('ascii'); // outputs: abcdefghijklmnopqrstuvwxyz 
buf.toString('ascii',0,5); // outputs: abcde 
buf .toString('utf8',0,5); // outputs: abcde 
buf .toString(undefined,0,5); // encoding defaults to 'utf8', out 
puts abcde 


buf.toJSON() 


返回 一 个 Buffer 实 例 的 JSON 形 式 。 JSON. stringify 被 隐 式 得 调用 当 转 换 Buffer 
实例 时 。 


例子 : 


var buf = new Buffer('test'); 
var json = JSON.stringify(buf); 


console.log(json); 
ih Ve Bulfer date 116, Ol ls 


var copy = JSON.parse(json, function(key, value) { 
return value && value.type === 'Buffer' 
? new Buffer(value.data) 
: value; 


P) 


console.log(copy); 
// <Buffer 74 65 73 74> 


buf[index] 


获取 或 设置 指定 位 置 的 和 八 位 字 节 。 这 个 值 是 指 单 个 字 节 ， 所 有 
在 0x00 到 OxFF 或 0 到 255 。 


> 
şe 
~ + 
JES) 


例子 : 复制 一 个 ASCII 字 符 串 到 一 个 buffer， 一 次 一 个 字 节 : 


str = "node.js"; 
buf = new Buffer(str.length); 


for (var i = 0; i < str.length ; i++) { 
buf[i] = str.charCodeAt(i); 
} 


console.log(buf); 


buf.equals(otherBuffer) 
e otherBuffer Buffer 


返回 一 个 布尔 值 表示 是 否 buf 4 otherBuffer 具有 相同 的 字 节 。 


buf.compare(otherBuffer) 


e otherBuffer Buffer 


返回 一 个 数字 表示 在 排序 上 buf 在 otherBuffer 之 前 ， 之 后 或 相同 。 


buf.copy(targetBuffer[, targetStart][, sourceStart][, 
sourceEnd]) 


e targetBuffer Buffer 将 要 进行 复制 的 Buffer 

e targetStart Number 可 选 ， 默 认为 0 

e sourceStart Number T > RUX 0 

e sourceEnd Number 72% > RUA buffer.length 


从 buf 中 的 指定 范围 复制 数据 到 targetBuffer FHECH’ ENXTARS 
的 。 


例子 : 创建 两 个 Buffer， 然 后 复制 buf1 的 第 16 字 节 到 19 字 节 到 buf2，buf2 的 偏 移 位 
置 从 第 8 字 节 开始 : 


buf1 = new Buffer(26); 
buf2 = new Buffer(26); 


fOr (var i 03) 1-926 imt) 
burifa] = 1+ 97 7// 97 2s ASCII a 
buf2[i] = 33; // ASCII ! 


buf1.copy(buf2, 8, 16, 20); 
console.log(buf2.toString('ascii', 0, 25)); 


77 S E eter ner 


例子 : 创建 一 个 单独 的 Buffer， 然 后 复制 数据 到 自身 的 一 个 重合 的 范围 。 


buf = new Buffer(26); 


fOr (Van f=" eat 26; att) fF 
bur [a] =a 07// 97 TS ASCII a 


buf.copy(buf, ©, 4, 10); 
console.log(buf.toString()); 


// efghijghijklmnopqrstuvwxyz 


buf.slice([start][, end]) 


e start Number T > RUJ 0 

e end Number 可 选 ， 默 认为 buffer .length 

e 2E — Fe 8 buffers] A T 40 A 49 HF buffer > 142% 
被 start 和 end 参数 所 偏 移 和 裁剪 。 


修改 这 个 新 的 buffer 的 切片 ， 也 会 改变 内 存 中 原来 的 buffer。 


例子 : 创建 一 个 ASCII 字 母 的 Buffer， 然 后 对 其 进行 slice ， 然 后 修改 源 Buffer 上 
的 二 丰年 下 


var buf1 = new Buffer(26); 


for (var a= 0 a <26 a+). tf 
buf1[i] = i + 97; // 97 is ASCII a 
} 


var buf2 = buf1.slice(0, 3); 
console.log(buf2.toString('ascii', 0, buf2.length)); 
buf1[0] = 33; 

console.log(buf2.toString('ascii', 0, buf2.length)); 


buf.indexOf(value[, byteOffset]) 


e value String Buffer 或 Number 

e byteOffset Number T > RUX 0 

e Return: Number 
行为 和 Array.indexOf() 相 似 。 接 受 一 个 字符 串 ，Buffer 或 数字 。 字 符 串 被 解释 为 
UTF8 编 码 ，Buffer 将 使 用 整个 buffer， 所 以 如 果 要 上 比较 部 分 的 Buffer 请 使 
用 Buffer.slice() ， 数 字 的 范围 需 在 0 到 255 之 间 。 


buf.readUInt8(offset[, noAssert]) 


e offset Number 
e noAssert Boolean T > RUA false 
e Return: Number 


根据 制定 偏 移 量 从 buffer 中 读 取 一 个 无 符号 8 位 整数 。 


将 noAssert 设置 为 true 将 会 跳 过 value 和 offset 的 检验 ， 这 意味 
A offset 将 可 能 超过 buffer 的 结束 人 位置， 默认 为 false 。 


例子 : 


var buf = new Buffer(4); 


buf[0] = 0x3; 
buf[1] = 0x4; 
buf[2] = 0x23; 
buf[3] = 0x42; 


for (ii = 0; ii < buf.length; ii++) { 
console.log(buf.readUInt8(1ii)); 
} 


buf.readUInt16LE(offset[, noAssert]) 


buf.readUInt16BE(offset[, noAssert]) 


e offset Number 
e noAssert Boolean T > RUA false 
e Return: Number 


根据 制定 偏 移 量 从 buffer 中 根据 特定 的 endian 字 节 序 读 取 一 个 无 符号 16 位 整数 。 


将 noAssert 设置 为 true 将 会 跳 过 value 和 offset 的 检验 ， 这 意味 
A offset 将 可 能 超过 buffer 的 结束 人 位置， 默认 为 false 。 


例子: 


var buf = new Buffer(4); 


buf[0] = 0x3; 
buf[1] = 0x4; 
buf[2] = 0x23; 
buf[3] = 0x42; 


console. log(buf . readUInti6BE(0)); 
console.log(buf.readUInt16LE(0)); 
console. log(buf.readUInt16BE(1)); 
console. log(buf.readUInti6LE(1)); 
console. log(buf .readUInt1i6BE(2)); 
console. log(buf.readUInti6LE(2)); 








buf.readUInt32LE(offset[, noAssert]) 


buf.readUInt32BE(offset[, noAssert]) 


e offset Number 
e noAssert Boolean T > RUA false 
e Return: Number 


根据 制定 偏 移 量 从 buffer 中 根据 特定 的 endian 字 节 序 读 取 一 个 无 符号 32 位 整数 。 


将 noAssert 设置 为 true 将 会 跳 过 value 和 offset 的 检验 ， 这 意味 
A offset 将 可 能 超过 buffer 的 结束 位 置 ， 默 认为 false 。 


例子 : 


var buf = new Buffer(4); 


buf[0] = 0x3; 
buf[1] = 0x4; 
buf[2] = 0x23; 
buf[3] = 0x42; 


console. log(buf . readUInt32BE(0)); 
console.log(buf.readUInt32LE(0)); 


buf.readint8(offset[, noAssert]) 


e offset Number 
e noAssert Boolean 可 选 ， 默 认为 ”false 
e Return: Number 


根据 制定 偏 移 量 从 buffer 中 读 取 一 个 有 符号 8 位 整数 。 


将 noAssert 设置 为 true 将 会 跳 过 value 和 offset 的 检验 ， 这 意味 
A offset 将 可 能 超过 buffer 的 结束 位 置 ， 默 认为 false 。 


\ 


作 和 buffer.readuUInts 相同 ， 除 非 buffer 内 容 中 有 和 包含 了 作为 2 的 补 码 的 有 符 
值 。 


op 半 


buf.readint16LE(offset[, noAssert]) 


buf.readint16BE(offset[, noAssert]) 


e offset Number 
e noAssert Boolean T > RUA false 
e Return: Number 


根据 制定 偏 移 量 从 buffer 中 根据 特定 的 endian 字 节 序 读 取 一 个 有 符号 16 位 整数 。 


将 noAssert 设置 为 true 将 会 跳 过 value 和 offset 的 检验 ， 这 意味 
A offset 将 可 能 超过 buffer 的 结束 人 位置， 默认 为 false 。 


运作 和 buffer.readuInti6 相同 ， 除 非 buffer 内 容 中 有 包含 了 作为 2 的 补 码 的 有 符 
值 。 


oh (x 


buf.readint32LE(offset[, noAssert]) 


buf.readint32BE(offset[, noAssert]) 


e offset Number 
e noAssert Boolean 可 选 ， 默 认为 false 
e Return: Number 


根据 制定 偏 移 量 从 buffer 中 根据 特定 的 endian 字 节 序 读 取 一 个 有 符号 32 位 整数 。 


将 noAssert 设置 为 true 将 会 跳 过 value 和 offset 的 检验 ， 这 意味 
A offset 将 可 能 超过 buffer 的 结束 位 置 ， 默 认为 false 。 


运作 和 buffer.readUInt32 相同 ， 除 非 buffer 内 容 中 有 包含 了 作为 2 的 补 码 的 有 符 
值 。 


oh [At 


buf.readFloatLE(offset[, noAssert]) 


buf.readFloatBE(offset[, noAssert]) 


e offset Number 
e noAssert Boolean 可 选 ， 默 认为 false 
e Return: Number 


根据 制定 偏 移 量 从 buffer 中 根据 特定 的 endian 字 节 序 读 取 一 个 32 位 浮 点 数 。 


将 noAssert 设置 为 true 将 会 跳 过 value 和 offset 的 检验 ， 这 意味 
着 offset 将 可 能 超过 buffer 的 结束 位 置 ， 默 认为 false 。 


例子 : 


var buf = new Buffer(4); 


buf [0] = 0x00; 
buf[1] = 0x00; 
buf[2] = 0x80; 
buf[3] = Ox3f; 


console.log(buf.readFloatLE(0)); 


‘/ 0x01 


buf.readDoubleLE(offset[, noAssert]) 


buf.readDoubleBE(offset[, noAssert]) 


e offset Number 
e noAssert Boolean T > RUA false 
e Return: Number 


根据 制定 偏 移 量 从 buffer 中 根据 特定 的 endian 字 节 序 读 取 一 个 64 位 双 精 度数 。 


将 noAssert 设置 为 true 将 会 跳 过 value 和 offset 的 检验 ， 这 意味 
A offset 将 可 能 超过 buffer 的 结束 位 置 ， 默 认为 false 。 


例子 : 


var buf = new Buffer(8); 


buf[0] = 0x55; 
buf[1] = 0x55; 
buf[2] = 0x55; 
buf[3] = 0x55; 
buf[4] = 0x55; 
buf[5] = 0x55; 
buf[6] = 0xd5 ， 
buf[7] = Ox3f; 


console.log(buf.readDoubleLE(0)); 


buf.writeUInt8(value, offset[, noAssert]) 


e value Number 

e offset Number 

e noAssert Boolean T > RUA false 
位 置 


向 buffer 的 指定 偏 移 写 入 value 。 注意 ， value 必须 是 一 个 合法 的 无 符 


号 8 位 整形 数 。 


将 noAssert 设置 为 true 将 跳 过 value 和 offset 的 验证 。 这 意 " 
着 value 可 能 会 过 大 ， 或 者 offset 超过 buffer ee value 被 丢弃 ， 
这 个 参数 除非 你 十 分 有 把 握 否 则 你 不 应 去 使 用 它 ， 上 默认 为 false e 


例子 : 


var buf = new Buffer(4); 
buf .writeUInt8(0x3, 0); 
buf .writeUInt8(0x4, 1); 
buf .writeUInt8(0x23, 2); 
buf .writeUInt8(0x42, 3); 


console.log(buf); 


buf.writeUInt16LE(value, offset[, noAssert]) 


buf.writeUInt16BE(value, offset[, noAssert]) 


e value Number 
e offset Number 
e noAssert Boolean 可 选 ， 默 认为 ”false 


向 buffer 的 指定 偏 移 位 置 根据 特定 的 endian 字 节 序 写 入 value ° iz 
意 ， value 必须 是 一 个 合法 的 无 符号 16 位 整形 数 。 


将 noAssert 设置 为 true 将 跳 过 value 和 offset 的 验证 。 这 意味 
A value 可 能 会 过 大 ， 或 者 offset 超过 buffer 的 末尾 导致 value 被 丢弃 ， 
这 个 参数 除非 你 十 分 有 把 握 否 则 你 不 应 去 使 用 它 ， 默 认为 false 。 


例子 : 


var buf = new Buffer(4); 
buf .writeUInti6BE(Oxdead, 0); 
buf .writeUInti6BE(Oxbeef, 2); 


console.log(buf); 


buf .writeUInti6LE(Oxdead, 0); 
buf .writeUInti6LE(Oxbeef, 2); 


console.log(buf); 


JC- 


buf.writeUInt32LE(value, offset[, noAssert]) 


buf.writeUInt32BE(value, offset[, noAssert]) 


e value Number 
e offset Number 
e noAssert Boolean 可 选 ， 默 认为 ”false 


向 buffer 的 指定 偏 移 位 置 根据 特定 的 endian 字 节 序 写 入 value ° iz 
意 ， value 必须 是 一 个 合法 的 无 符号 32 位 整形 数 。 


将 noAssert 设置 为 true 将 跳 过 value 和 offset 的 验证 。 这 意味 
着 value 可 能 会 过 大 ， 或 者 offset 超过 buffer 的 末尾 导致 value 被 丢弃 ， 
这 个 参数 除非 你 十 分 有 把 握 否 则 你 不 应 去 使 用 它 ， 默 认为 false 。 


例子 : 


var buf = new Buffer(4); 
buf .writeUInt32BE(0xfeedface, 0); 


console. log(buf); 
buf .writeUInt32LE(0xfeedface, 0); 


console.log(buf); 


buf.writelnt8(value, offset[, noAssert]) 


e value Number 
e offset Number 
e noAssert Boolean 72° RUA false 


向 buffer 的 指定 偏 移 位 置 中 写 入 value 。 注意 ， value 必须 是 一 个 合法 的 无 


符号 32 位 整形 数 。 


将 noAssert 设置 为 true 将 跳 过 value 和 offset 的 验证 。 这 意味 
着 value 可 能 会 过 大 ， 或 者 offset 超过 buffer 的 末尾 导致 value REF ? 
这 个 参数 除非 你 十 分 有 把 握 否 则 你 不 应 去 使 用 它 ， 默 认为 false 。 


\ 


作 和 buffer.writeUInts 相同 ， 除 非 buffer 内 容 中 有 包含 了 作为 2 的 补 码 的 有 符 
值 。 


中 六 


buf.writelnt16LE(value, offset[, noAssert]) 


buf.writelnt16BE(value, offset[, noAssert]) 


e value Number 
e offset Number 
e noAssert Boolean 可 选 ， 默 认为 false 


向 buffer 的 指定 偏 移 位 置 根据 特定 的 endian 字 节 序 写 入 value ° È 
意 ， value 必须 是 一 个 合法 的 有 符号 16 位 整形 数 。 


将 noAssert 设置 为 true 将 跳 过 value 和 offset 的 验证 。 这 意味 
A value 可 能 会 过 大 ， 或 者 offset 超过 buffer 的 末尾 导致 value 被 丢弃 ， 
这 个 参数 除非 你 十 分 有 把 握 否 则 你 不 应 去 使 用 它 ， 默 认为 false 。 


运作 和 buffer.writeUInt16 相同 ， 除 非 buffer 内 容 中 有 包含 了 作为 2 的 补 码 的 有 
符号 值 


buf.writelnt32LE(value, offset[, noAssert]) 


buf.writelnt32BE(value, offset[, noAssert]) 


e value Number 
e offset Number 
e noAssert Boolean T > RUA false 


向 buffer 的 指定 偏 移 位 置 根据 特定 的 endian 字 节 序 写 入 value ° 注 


sa 


意 ， value 必须 是 一 个 合法 的 有 符号 32 位 整形 数 。 


将 noAssert 设置 为 true 将 跳 过 value 和 offset 的 验证 。 这 意味 
A value 可 能 会 过 大 ， 或 者 offset 起 过 buffer 的 末尾 导致 value 被 丢弃 ， 
这 个 参数 除非 你 十 分 有 把 握 否 则 你 不 应 去 使 用 它 ， 默 认为 false 。 


运作 和 buffer.writeUInt32 相同 ， 除 非 buffer 内 容 中 有 包含 了 作为 2 的 补 码 的 有 
符号 值 。 


buf.writeFloatLE(value, offset[, noAssert]) 


buf.writeFloatBE(value, offset[, noAssert]) 


e value Number 
e offset Number 
e noAssert Boolean T > RUA false 


向 buffer 的 指定 偏 移 位 置 根据 特定 的 endian 字 节 序 写 入 value ° È 
意 ， value 必须 是 一 个 合法 的 32 位 浮上 点数 。 


将 noAssert 设置 为 true 将 跳 过 value 和 offset 的 验证 。 这 意味 
A value 可 能 会 过 大 ， 或 者 offset 超过 buffer 的 末尾 导致 value REF ? 
这 个 参数 除非 你 十 分 有 把 握 否 则 你 不 应 去 使 用 它 ， 默 认为 false 。 


例子 : 


var buf = new Buffer(4); 
buf .writeFloatBE(Oxcafebabe, 0); 


console.log(buf); 
buf .writeFloatLE(Oxcafebabe, 0); 


console.log(buf); 


buf.writeDoubleLE(value, offset[, noAssert]) 


buf.writeDoubleBE(value, offset[, noAssert]) 


e value Number 
e offset Number 
e noAssert Boolean T > RUA false 


向 buffer 的 指定 偏 移 位 置 根据 特定 的 endian 字 节 序 写 入 value ° È 
意 ， value 必须 是 一 个 合法 的 64 位 双 精 度数 。 


将 noAssert 设置 为 true 将 跳 过 value 和 offset 的 验证 。 这 意味 
A value 可 能 会 过 大 ， 或 者 offset 超过 buffer 的 末尾 导致 value 被 丢弃 ， 
这 个 参数 除非 你 十 分 有 把 握 否 则 你 不 应 去 使 用 它 ， 默 认为 false 。 


例子 : 


var buf = new Buffer(8); 
buf .writeDoubleBE(Oxdeadbeefcafebabe, 0); 


console. log(buf); 
buf .writeDoubleLE(Oxdeadbeefcafebabe, 0); 


console.log(buf); 


/1/ eRuffor A2 ah E h7 dod fa EGF AZs 
// <Buffer 43 eb d5 b7 dd f9 5f d7> 


// <Buffer d7 5f f9 dd b7 d5 eb 43> 


buf.fill(value[, offset][, end]) 


e value 
e offset Number 可 选 
e end Number 可 选 


使 用 指定 的 value 填充 buffer。 如 果 offset (默认 为 0) 和 end (默认 
为 buffer.length ) 没有 指定 ， 将 会 填充 整个 buffer 。 


var b = new Buffer(50); 
Det Le hn”) 


buffer.values() 


创建 一 个 buffer 内 的 值 (bytes) 的 迭代 器 。 这 个 函数 会 被 自动 调用 当 buffer 被 用 
a GRADE 


buffer.keys() 


创建 一 个 buffer 的 索引 的 迭代 器 。 


buffer.entries() 


创建 一 个 [index, byte] 数 组 迭代 器 。 


bufferINSPECT_MAX_BYTES 


Number 144 : 50 


表示 有 多 少 字 节 会 被 返回 当 调 用 buffer.inspect() 时 。 它 可 以 被 用 户 的 模块 所 
fi te © 


注意 这 是 一 个 由 require('buffer') 返回 的 buffer 模 块 的 属性 ， 并 不 是 全 
局 Buffer 3t % AXbufferS 1] 49 o 
、 > ge 
ES6 和 迭代 器 
Buffers 可 以 被 ES6 的 for..of 语法 迭代 : 
var buf = new Buffer([1, 2, 3]); 


for (var b of buf) 
console.log(b) 


另外 的 ， buffer.values() ， buffer.keys() 和 buffer.entries() 方法 都 
可 以 被 用 来 创建 迭代 器 。 


Class: SlowBuffer 
返回 一 个 不 被 池 管 理 的 Buffer ° 


为 了 避免 创建 许多 单个 的 被 分 配 内 存 的 小 Buffer 的 垃圾 回收 开销 。 默 认得 ， 分 配 小 
于 4KB 的 空间 将 会 被 从 一 个 更 大 的 被 分 配 好 内 存 的 对 象 (allocated object) 中 切片 
(sliced) 得 到 。 这 个 方法 改进 了 性 能 以 及 内 存 占用 ， 为 V8 的 垃圾 回收 机 制 不 再 需 
要 追踪 和 清理 许多 的 小 对 象 。 


当 开 发 者 需要 将 池 中 一 小 块 数据 保留 不 确定 的 一 段 时 间 ， 较 为 妥当 的 办 法 是 用 
SlowBuffer 创建 一 个 不 被 池 管 理 的 Buffer 实例 并 将 相应 数据 拷贝 出 来 。 


Buffer 


// need to keep around a few small chunks of memory 
var store = []; 


socket.on('readable', function() { 
var data = socket.read(); 
// allocate for retained data 
var sb = new SlowBuffer(10); 
// copy the data into the new allocation 
data.copy(sb, 0, 0, 10); 
store.push(sb); 
}); 


请 谨 懂 使 用 ， 仅 作为 开发 者 察觉 到 在 应 用 中 有 过 度 的 内 存 保留 时 的 最 后 手段 。 


Child Process 


稳定 度 : 2 -稳定 
node.js 通过 child_process 模块 提供 了 三 向 的 popen 功能 。 


可 以 无 阻塞 地 通过 子 进程 的 stdin > stdout 和 stderr 以 流 的 方式 传递 数据 。 
(注意 某 些 程序 在 内 部 使 用 了 行 缓冲 MO， 这 不 会 影响 node.js ， 但 是 这 意味 你 传 
递 给 子 进程 的 数据 可 能 不 会 在 第 一 时 间 被 消费 ) 。 


可 以 通 
过 require('child_process').spawn() 或 require('child_process' ).fork 
O 创建 子 进程 。 这 两 者 间 的 语义 有 少许 差别 ， 将 会 在 后 面 进行 解释 。 


当 以 写 脚 本 为 目的 时 ， 你 可 以 会 觉得 使 用 同步 版 本 的 方法 会 更 方便 。 


Class: ChildProcess 
ChildProcess 是 一 个 EventEmitter 。 


子 进程 总 是 有 三 个 与 之 相关 的 
流 。 child.stdin ， child.stdout 和 child.stderr 。 他 们 可 能 会 共享 父 进 
程 的 stdio 流 ? 或 者 也 可 以 是 独立 的 被 导 流 的 Fut Be 9 


ChildProcess 类 并 不 是 用 来 直接 被 使 用 的 。 应 当 使 
用 spawn() , exec() , execFile() 或 fork() 方法 来 创建 一 个 子 进程 实例 。 
Event: ‘error’ 
e err Error ik & 
REF: 


进程 不 能 被 创建 时 ， 进 程 不 能 杀 死 时 ， 给 予 进程 发 送信 息 失败 时 。 注意 exit ¥ 
件 在 一 个 错误 发 生 后 可 能 触发 。 如 果 你 同时 监听 了 这 两 个 事件 来 触发 一 个 函数 ， 需 
要 记 住 不 要 让 这 个 函数 被 触发 两 次 。 


参阅 ChildProcess.kill() 和 ChildProcess.send() ° 


Event: ‘exit' 


。 code Number 如 果 进 程 正 常 退出 ， 则 为 退出 码 。 如 果 进 程 被 父 进程 杀 死 ， 则 为 
被 传递 的 信号 字符 串 。 这 个 事件 将 在 子 进程 结束 运行 时 被 触发 。 


注意 子 进 程 的 stdio 流 可 能 仍 为 打开 状态 。 


还 需要 注意 的 是 ， node.js 已 经 为 我 们 添加 了 'SIGINT' 信 号 和 'SIGTERM' 信 号 的 
事件 处 理 函 数 ， 所 以 在 父 进程 发 出 这 两 个 信号 时 ， 进 程 将 会 退出 。 


参阅 waitpid(2) ° 


Event: ‘close’ 


e code Number 如 果 进 程 正 常 退出 ， 则 为 退出 码 。 如 果 进 程 被 父 进程 杀 死 ， 则 为 
被 传递 的 信号 字符 囊 。 这 个 事件 将 在 子 进程 结束 运行 时 被 触发 。 这 个 事件 将 会 
在 子 进程 的 stdio 流 都 关闭 时 触发 。 这 是 与 exit 的 区 别 ， 因 为 可 能 会 有 几 
个 进程 共享 同样 的 stdio 流 。 


Event: ‘disconnect’ 

在 父 进 程 或 子 进 程 中 使 用 ,disconnect() 方法 后 这 个 事件 会 触发 。 在 断 开 之 后 ， 
将 不 能 继续 相互 发 送信 息 ， 并 且 子 进程 的 ,connected 属性 将 会 是 false 。 
Event: ‘message’ 


e message Object 一 个 已 解析 的 JSON 对 象 或 一 个 原始 类 型 值 
e sendHandle Handle object 一 个 Socket 或 Server WR 


通过 .send(message, [sendHandle]) 发 送 的 信息 可 以 通过 监听 message 事件 


获取 到 。 


child.stdin 
e Stream object 


一 个 代表 了 子 进 程 的 stdin 的 可 写 流 。 通 过 end() 方法 关闭 此 流 可 以 终止 子 进 


is 


FE © 


如 果子 进程 通过 spawn 创建 时 stdio 没有 被 设置 为 pipe ， 那 么 它 将 不 会 被 创 
建 。 


child.stdin 为 child.stdio 中 对 应 元 素 的 快捷 引用 。 它 们 要 么 都 指向 同一 个 
对 象 ， 要 么 都 为 null 。 


child.stdout 
e Stream object 
一 个 代表 了 子 进程 的 stdout 的 可 读 流 。 


如 果子 进程 通过 spawn 创建 时 stdio 没有 被 设置 为 pipe ， 那 么 它 将 不 会 被 创 
建 o 

child.stdout 为 child.stdio 中 对 应 元 素 的 快捷 引用 。 它 们 要 么 都 指向 同一 个 
对 象 ， 要 么 都 为 null。 


child.stderr 
e Stream object 
一 个 代表 了 子 进 程 的 stderr 的 可 读 流 。 


如 果子 进程 通过 spawn 创建 时 stdio 没有 被 设置 为 pipe ， 那 么 它 将 不 会 被 创 
建 o 


child.stderr 为 child.stdio 中 对 应 元 素 的 快捷 引用 。 它 们 要 么 都 指向 同一 个 
对 象 ， 要 么 都 为 null 。 


child.stdio 
e Array 


八 包 含 了 子 进 程 的 管道 的 稀疏 数组 ， 元 素 的 位 置 对 应 着 利用 spawn 创建 子 进程 
时 stdio 配置 参数 里 被 设置 为 pipe 的 位 置 。 注 意 索 引 为 0-2 的 流 分 别 
与 ChildProcess.stdin ， 
ChildProcess.stdout 和 ChildProcess.stderr 引用 的 是 相同 的 对 象 。 


在 下 面 的 例子 中 ， 在 stdio 参数 中 只 有 索引 为 1 的 元 素 被 设置 为 了 pipe ， 所 以 
父 进 程 中 只 有 child.stdio[1] 是 一 个 流 ， 其 他 的 元 素 都 为 null 。 


var assert = require('assert'); 
var fs = require('fs'); 
var child_process = require('child_process'); 


child = child_process.spawn('ls', { 
stdio: [ 
©, // use parents stdin for child 
‘pipe’, // pipe child's stdout to parent 
fs.openSync('err.out', *w') // direct child's stderr to 
file 
] 
}); 


assert.equal(child.stdio[0], null); 
assert.equal(child.stdio[0], child.stdin); 


assert(child.stdout); 
assert.equal(child.stdio[1], child.stdout); 


assert.equal(child.stdio[2], null); 
assert.equal(child.stdio[2], child.stderr); 


child.pid 
e Integer 
子 进程 的 PID ° 


例子 : 


var spawn = require('child_process').spawn, 
grep spawn('grep', ['ssh']); 


console.log('Spawned child pid: ' + grep.pid); 
grep.stdin.end(); 


child.connected 


e Boolean 在 .disconnect 方法 被 调用 后 将 会 被 设置 为 false ° 


Æ .connected 属性 为 false ， 那 么 将 不 能 再 向 子 进程 发 送信 息 。 


child.kill([signal]) 


e signal String 


给 子 进 程 传递 一 个 信号 。 如 果 没 有 指定 任何 和 参数， 那么 将 发 送 'SIGTERM 给 子 进 
程 。 更 多 可 用 的 信号 请 参阅 signal(7) 。 


var spawn = require('child_process').spawn, 
grep = spawn('grep', ['ssh']); 


grep.on('close', function (code, signal) { 
console.log('child process terminated due to receipt of signal 
' + signal); 


}); 


// send SIGHUP to process 
grep.kill('SIGHUP'); 


在 信号 不 能 被 送 达 时 ， 可 能 会 产生 一 个 error 事件 。 给 一 个 已 经 终止 的 子 进程 发 
a= ee 误 ， a 如 果 该 子 进程 的 PID 已 
经 被 重新 分 配给 了 另 一 个 进程 ， 那 么 信号 会 被 传递 到 另 一 个 进程 中 。 大 家 可 以 
猜想 这 将 会 y 样 的 情况 。 


注意 这 个 函数 仅仅 是 名 字 叫 k 训 ， 给 子 进程 发 送 的 信号 可 能 不 
数 仅 仅 只 是 给 子 进 程 发 送 一 个 信号 


去 关闭 它 的 。 这 个 逻 


ie 


参阅 kill(2) ° 


child.send(message[, sendHandle]) 


e message Object 
e sendHandle Handle object 


当 使 用 child_process.fork() 时 ， 你 可 以 使 用 child.send(message, 
[sendHandle]) 向 子 进程 发 送信 息 ， 子 进程 里 会 触发 message 事件 当 收 到 信 
时 。 


(> 


例子 : 


var cp = require('child_process'); 
var n = cp.fork(__dirname + '/sub.js'); 


n.on('message', function(m) { 
console.log('PARENT got message:', m); 
}); 


n.send({ hello: 'world' }); 


子 进 程 代码 ，sub.js 可 能 看 起 来 类 似 这 样 


process.on('message', function(m) { 
console.log('CHILD got message:', m); 
}); 


process.send({ foo: 'bar' }); 


在 子 
时 ， ， 信 息 hon 将 以 对 象 的 形 式 返 


请 注意 父 进 程 ， 子 进程 中 的 send() 方法 都 是 同步 的 ， 所 以 发 送 大 量 数据 是 不 被 建 
道 


议 的 (可 以 使 用 管道 代替 ， 参 阅 child_process.spawn ) ° 


发 送 {cmd: 'NODE_foo'} 信息 时 是 一 个 特殊 情况 。 所 有 的 在 cmd 属性 中 包 

了 NODE_ 前 级 的 信息 都 不 会 触发 message 事件 ， 因 为 这 是 node.js are 的 
内 部 信息 。 包 含 这 个 前 组 的 信息 都 会 触发 internalMessage 事件 。 请 避免 使 用 这 
个 事件 ， 它 在 改变 的 时 候 不 会 收 到 通知 。 


child.send() 的 sendHandle 参数 时 用 来 给 另 一 个 进程 发 送 一 个 TCP 服 务 器 或 
一 个 socket 的 。 将 之 作为 第 二 个 参数 传 入 ， 子 进程 将 在 message 事件 中 会 收 到 
这 个 对 象 。 


如 果 信 息 不 能 被 发 送 的 话 将 会 触发 一 个 error 事件 ， 比 如 子 进程 已 经 退出 了 。 
例子 : 发 送 一 个 server WH 


var child = require('child_process').fork('child.js'); 


// Open up the server object and send the handle. 


var server = require('net').createServer(); 
server.on('connection', function (socket) { 


socket.end('handled by parent'); 


}); 


server.listen(1337, function() { 
child.send('server', server); 


}); 


子 进 程 将 会 收 到 server HR: 


process.on('message', function(m, 


if (m === 'server') { 


server.on('connection', 


function (socket) { 


socket.end('handled by child'); 


4); 


注意 这 个 server 现在 已 经 被 父 进 


程 处 理 也 可 能 被 子 进程 处 理 。 


程 和 子 进程 所 共享 


server) { 


， 这 意味 着 链接 将 可 能 


对 于 dgram 服务 器 ， 流 程 也 是 完全 一 样 的 。 使 用 message 事件 而 不 


是 connection 事件 ， 使 用 server.bind 问 不 是 server.listen 


持 UNIX 平台 ) 。 
例子 : 发 送 一 个 socket WH 


以 下 是 发 送 一 个 socket 的 例子 。 创 建 


A 74.125.127.100 的 链接 通 


过 将 socket 发 送 


他 的 socket 则 被 发 送 给 "normal" 子 进程 。 


了 两 个 子 进 程 。 并 且 将 地 址 
关 给 "special" 子 进程 来 视 作 VIP © 


(目前 只 


被 父 


进 


其 


var normal = require('child_process').fork('child.js', ['normal' 
l); 
var special = require('child_process').fork('child.js', ['specia 


1']); 


// Open up the server and send sockets to child 
var server = require('net').createServer(); 
server.on('connection', function (socket) { 


M th ES S el Vir. 

if (socket.remoteAddress === '74.125.127.100') { 
special.send('socket', socket); 
return; 

} 

// just the usual dudes 

normal.send('socket', socket); 


}); 


server.listen(1337); 


rchailda is: e 

ae 
process.on('message', function(m, socket) { 

if (m === 'socket') { 

socket.end('You were handled as a ' + process.argv[2] + ' pe 

PSONE) 

} 
DE 


Ea E N e E A 了 子 进程 ， 那 么 父 进程 将 不 能 追踪 到 这 
个 socket 被 删除 的 时 间 ， 这 个 情况 下 .connections 属性 将 会 成 为 null 。 在 
个 情况 下 同样 也 不 推荐 使 用 .maxConnections 属性 。 


child.disconnect() 


a 进程 与 子 进程 问 ， 它 让 子 进程 非常 优雅 地 退出 ， 因 为 已 经 活跃 的 
。 在 调用 了 这 个 方法 后 ， 父 进程 和 子 进程 的 ,connected 标签 都 会 被 设置 
false ， 将 不 能 再 发 送信 "a o 


disconnect 事件 在 进程 不 再 有 消息 接收 时 触发 。 


注意 ， 当 子 进 程 中 有 和 与 父 进程 通信 的 IPC 信 道 时 ， 你 也 可 以 在 子 进程 中 调 


用 process.disconnect() ° 


异步 进程 的 创建 


以 下 方法 遵循 普遍 的 异步 编程 模式 (接受 一 个 回调 函数 或 返回 一 


个 EventEmitter ) ° 


child_process.spawn(command[, args][, options]) 


e command String 将 要 运行 的 命令 
e args Array 字符 串 参 数 数组 


e options Object 


o cwd String 子 进 程 的 当前 工作 目录 
o env Object 环境 变量 键 值 对 
o stdio Array|String 子 进 程 的 stdio 配 置 
o detached Boolean 这 个 子 进程 将 会 变 成 进程 组 的 领导 
o uid Number 设置 用 户 进 程 的 ID 
o gid Number 设置 进程 组 的 ID 
e return: ChildProcess object 


利用 给 定 的 命令 以 及 参数 执行 一 个 新 的 进程 ， 如 果 没 有 参数 数组 ， 那 么 args HR 
认 是 一 个 空 数组 。 


第 三 个 参数 时 用 来 指定 以 为 额外 的 配置 ， 以 下 是 它 的 默认 值 : 


{ cwd: undefined, 
env: process.env 


} 
使 用 cwd 来 指定 子 进 程 的 工作 目录 。 如 果 没 有 指定 ， 默 认 值 是 当前 父 进 程 的 工作 
目录 。 
使 用 env 来 指定 子 进 程 中 可 用 的 环境 变量 ， 默 认 值 是 process.env ° 


Example of running Is -Ih /usr, capturing stdout, stderr, and the exit code: 一 个 运 
行 ls -lh /usr ， 获 取 stdout > stderr 和 退出 码 得 例子 : 


var spawn 
ls 
ls.stdout. 


console. 


}); 


ls.stderr. 
console. 


}); 


hild Drnracec 
Child Processes 


= require('child_process').sSpawn, 
spawn('ls', ['-lLh', '/usr']); 


on('data', function (data) { 
log('stdout: ' + data); 


on('data', function (data) { 
log('stderr: ' + data); 


ls.on('close', function (code) { 


console. 


}); 


log('child process exited with code ' + code); 


例子 : 一 个 非常 精巧 的 运行 ps ax | grep ssh 的 方式 


P 
LZ ( 
40 


var spawn = require('child_process').spawn, 
ps = spawn('ps', ['ax']), 
grep = spawn('grep', ['ssh']); 


ps.stdout.on('data', function (data) { 
grep.stdin.write(data); 


}); 
ps.stderr.on('data', function (data) { 
console.log('ps stderr: ' + data); 
}); 
ps.on('close', function (code) { 
if (code !== 0) { 
console.log('ps process exited with code ' + code); 
} 
grep.stdin.end(); 
}); 


grep.stdout.on('data', function (data) { 
console.log('' + data); 


}); 

grep.stderr.on('data', function (data) { 
console.log('grep stderr: ' + data); 

}); 

grep.on('close', function (code) { 
if (code !== 0) { 

console.log('grep process exited with code ' + code); 

} 

}); 


一 个 检查 执行 失败 的 例子 : 


var spawn = require('child_process').spawn, 
child = spawn('bad_command'); 


child.on('error', function (err) { 
console.log('Failed to start child process.'); 


}); 


options.stdio 
作为 快捷 方式 ， stdio 的 值 可 以 是 一 下 字符 串 之 一 : 


'pipe' - [pipe', ‘pipe’, 'pipe'], 这 是 默认 值 'ignore' - ['ignore’, ‘ignore’, 'ignore'] 'inherit' 
- [process.stdin, process.stdout, process.stderr] X[0,1,2] 


否则 ， child_process.spawn() 的 stdio 参数 时 一 个 数组 ， 数 组 中 的 每 一 个 索 
引 的 对 应 子 进程 中 的 一 个 文件 标识 符 。 可 以 是 下 列 值 之 一 : 


'pipe' - 创建 一 个 子 进程 与 父 进程 之 间 的 管道 ， 管 道 的 父 进程 端 已 父 进程 

的 child_process 对 象 的 属性 ( ChildProcess.stdio[fd] ) 暴露 给 父 进程 。 
为 文件 表示 (fds) 0-2 创建 的 管道 也 可 以 通 

过 ChildProcess.stdin ， ChildProcess.stdout 和 ChildProcess.stderr 
分 别 访问 。 


'ipc' - 创建 一 个 子 进 程 和 父 进程 间 传输 信息 /文件 描述 符 的 I|PC 信 道 。 一 个 子 进程 最 
多 可 能 有 一 个 IPC stdio 文件 描述 符 。 设 置 该 选项 将 激 

活 ChildProcess.send() 方法 。 如 果子 进程 向 此 文件 描述 符 中 写 入 JSON 数 据 ， 
则 会 触发 ChildProcess.on('message') 。 如 果子 进程 是 一 个 node.js 程序 ， 
那么 IPC 信 道 的 存在 将 会 激活 process.send() 和 process.on('message') ° 


'ignore' - 不 在 子 进程 中 设置 文件 描述 符 。 注 意 node.js 总 是 会 为 通过 spawn 创 
建 的 子 进程 打开 文件 描述 符 (fd) 0 - 2。 如 果 这 其 中 任意 一 项 被 设置 为 

J ignore > node.js 会 打开 /dev/null 并 将 其 附 给 予 进程 对 应 的 文件 描述 符 
(fd) ° 


Stream object - 与 子 进程 共享 一 个 与 ty， 文 件 ，socket， 或 管道 相关 的 可 读 /可 写 
流 。 该 流 底层 (underlying) 的 文件 标识 在 子 进程 中 被 复制 给 stdio 数 组 索引 对 应 的 
文件 描述 符 (fd) 。 


Positive integer - 该 整形 值 被 解释 为 父 进 程 中 打开 的 文件 标识 符 。 他 与 子 进程 共 
， 和 Stream 被 共享 的 方式 相似 。 


null, undefined - 使 用 默认 值 。For 对 于 stdio fds 0,1,2 (或 者 
说 stdin , stdout 和 stderr ) ，pipe 管 道 被 建立 。 对 于 fd 3 及 往 后 ， 默 认 


为 ignore 。 


例子 : 
var spawn = require('child_process').spawn; 


// Child will use parent's stdios 
spawn('prg', [], { stdio: ‘inherit’ }); 


// Spawn child sharing only stderr 
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] }); 


// Open an extra fd=4, to interact with programs present a 
// startd-style interface. 
spawn( prg T], { stdio: [’ pipe’, null, null, null, ‘pipe’] }); 


options.detached 


如 果 detached 选项 被 设置 ， 子 进程 将 成 为 新 进程 组 的 领导 。 这 使 得 在 父 进程 退出 
后 ， 子 进 ee 


默认 情况 下 ， 父 进程 会 等 待 脱离 了 的 子 进程 退出 。 要 阻止 父 进程 等 待 一 个 给 出 的 子 
进程 ， 请 使 用 child.unref() 方法 ， 则 父 进 程 的 事件 循环 的 计数 中 将 不 包含 这 个 
子 进程 。 


一 个 脱离 的 长 时 间 运 行 的 进程 ， 以 及 将 它 的 输出 重 定向 到 文件 中 的 例子 


var fs = require('fs'), 
Spawn = require('child_process').spawn, 
out = fs.openSync('./out.log', 'a'), 
err = fs.openSync('./out.log', 'a'); 


var child = spawn('prg', [], { 
detached: true, 
stdio: [ 'ignore', out, err | 


J); 


child.unref(); 


当 使 用 detached 选项 创建 一 个 长 时 间 运 行 的 进程 时 ， 进 程 不 会 保持 运行 除非 向 它 
提供 了 一 个 不 连接 到 父 进程 的 stdio 的 配置 o 如 果 继 承 了 父 进 程 的 arto ， 那 
么 子 进 程 将 会 继续 附着 在 控制 终端 。 


参阅 : child_process.exec() 和 child_process.fork() 


child_process.exec(command[, options], callback) 
e command String 将 要 运行 的 命令 ， 参 数 使 用 空格 隔 开 
e options Object 


o cwd String 子 进 程 的 当前 工作 目录 

o env Object 环境 变量 键 值 对 

o encoding String 字符 编码 (Rik: 'Utf8') 

o shell String 将 要 执行 命令 的 Shell (RU: 在 UNIX 中 为 /bin/sh ， 在 
Windows 中 为 cmd.exe ，Shell 应 当 能 识别 -c 开关 在 UNIX 中 ， 或 /s 
/c 在 Windows 中 。 在 Windows 中 ， 命 令 行 解析 应 当 能 兼容 cmd.exe ) 

o timeout Number 起 时 时 间 (默认 : 0) 

o maxBuffer Number 在 stdout 或 stderr 中 允许 存在 的 最 大 缓冲 (二进制 ) > 
如 果 超 出 那么 子 进程 将 会 被 杀 死 (RU: 200*1024) 

o killSignal String 结束 信号 (默认 : 'SIGTERM') 

o uid Number 设置 用 户 进程 的 ID 

o gid Number 设置 进程 组 的 ID 

e callback Function 


o error Error 
o stdout Buffer 
o stderr Buffer 


e Return: ChildProcess object 
在 Shell 中 运行 一 个 命令 ， 并 缓存 命令 的 输出 。 


var exec = require('child_process').exec, 
child; 


child = exec('cat *.js bad_file | wc -1', 
function (error, stdout, stderr) { 


console.log('stdout: ' + stdout); 

console.log('stderr: ' + stderr); 

if (error !== null) { 
console.log('exec error: ' + error); 

} 


4); 


回调 函数 的 参数 是 error ， stdout ， stderr 。 在 成 功 时 ， error 将 会 
是 null 。 在 发 生 错 误 时 ， error 将 会 是 一 个 Error 实例 ， error.code 将 会 
是 子 进程 的 退出 码 ， error.signal 将 会 被 设置 为 结束 进程 的 信号 。 


第 二 个 可 选 的 参数 用 于 指定 一 些 配 置 ， 默 认 值 为 : 


{ encoding: 'utf8', 
timeout: 0, 
maxBuffer: 200*1024, 
killSignal: 'SIGTERM', 
cwd: null, 
env: null } 


如 果 timeout 大 于 0， 那 么 子 进 程 在 运行 时 超过 timeout 时 将 会 被 杀 死 。 子 进程 
使 用 killSignal 信号 结束 (默认 为 :'SIGTERM') 。 maxBuffer 指定 

了 stdout > stderr 中 的 最 大 数据 量 (FP) ， 如 果 超 过 了 这 个 数据 量子 进程 
也 会 被 杀 死 。 


注意 : 不 像 POSIX 中 的 exec() ， child_process.exec() 不 替换 已 经 存在 的 进 
程 并 且 使 用 一 个 SHELL 去 执行 命令 。 


child_process.execFile(file[, args][, options][, callback]) 


。 file String 将 要 运行 的 命令 ， 参 数 使 用 空格 隔 开 
。 args 字符 囊 参数 数组 


e options Object -cwd String 子 进程 的 当前 工作 目录 -env Object 环境 变量 键 值 
对 


o encoding String 字符 编码 (默认 : "utf8') 
o timeout Number 起 时 时 间 (默认 : 0) 
o maxBuffer Number 在 stdout 或 stderr 中 允许 存在 的 最 大 缓冲 (二进制 ) ， 
如 果 超 出 那么 子 进 程 将 会 被 杀 死 (Rik: 200*1024 ) 
o killSignal String 结束 信号 (默认 : 'SIGTERM') 
o uid Number 设置 用 户 进程 的 ID 
o gid Number 设置 进程 组 的 ID 
e callback Function 


o error Error 
o stdout Buffer 
o stderr Buffer 
e Return: ChildProcess object 


这 个 方法 和 Child_process.exec() 相似 ， 除 了 它 不 是 使 用 一 个 子 SHELL 执 行 命 
令 而 是 直接 执行 文件 。 因 此 它 比 child_process.exec 稍 许 精简 一 些 。 它 们 有 相 
同 的 配置 。 


child_process.fork(modulePath[, args][, options]) 


e modulePath String 将 要 在 子 进 程 中 运行 的 模块 
e args Array 字符 串 参 数 数 组 


e options Object 


。 cwd String 子 进 程 的 当前 工作 目录 

e env Object 环境 变量 键 值 对 

e execPath String 创建 子 进程 的 可 执行 文件 

e execArgy Array 子 进 程 的 可 执行 文件 的 字符 串 参 数 数 组 (默认: 


process.execArgv ) 

e silent Boolean # RA true ， 子 进程 的 stdin > stdout 和 stderr 将 会 
被 关联 至 父 进 程 ， 和 否则， 它们 将 会 从 父 进 程 中 继承 。 (默认 为 false ) 

e uid Number 设置 用 户 进程 的 ID 

e gid Number 设置 进程 组 的 ID 


Return: ChildProcess object 


这 个 方法 是 spawn() 的 特殊 形式 ， 用 于 创建 node.js 进程 。 返 回 的 对 象 除了 拥 
有 ChildProcess 实例 的 所 有 方法 ， 还 有 一 个 内 建 的 通信 信道 。 详 情 参 
阅 child.send(message, [sendHandle]) ° 

这 些 node.js 子 进 程 都 是 全 新 的 V8 实 例 。 每 个 新 的 node.js 进程 都 至 少 需要 
30ms 启 动 以 及 10mb 的 内 存 。 所 以 ， 你 不 能 无 休止 地 创建 它们 。 

options 对 象 中 的 execPath 属性 可 以 用 非 当 前 node.js 可 执行 文件 来 创建 子 
进程 。 这 需要 小 心 使 用 ， 并 且 缺 省 情况 下 会 使 用 子 进 程 上 的 NODE_CHANNEL_FD 环 
境 变量 所 指定 的 文件 描述 符 来 通讯 。 该 文件 描述 符 的 输入 和 输出 假定 为 以 行 分 割 的 
JSON 对 象 。 


注意 : 不 像 POSIX 中 的 fork() > child_process.fork() 不 会 复制 当前 进程 。 


同步 进程 创建 
以 下 这 些 方法 是 同步 的 ， 意 味 着 它们 会 阻塞 事件 循环 。 直 到 被 创建 的 进程 退出 前 ， 


代码 都 将 停止 执行 。 

些 同步 方法 对 简化 大 多 数 脚本 任务 都 十 分 有 用 ， 并 对 简化 应 用 配置 的 加 载 /执行 也 
之 分 有 用 。 
child_process.spawnSync(command{, args][, options]) 


e command 将 要 运行 的 命令 
e args Array 字符 串 参 数 数 组 


e options Object 


o cwd String 子 进 程 的 当前 工作 目录 
o input String|Buffer 将 要 被 作为 stdin 传 入 被 创建 的 进程 的 值 ， 提 供 这 个 
值 将 会 覆盖 stdio[0] 


o stdio Array 子 进 程 的 stdio 配置 

o env Object 环境 变量 键 值 对 

o uid Number 设置 用 户 进 程 的 ID 

o gid Number 设置 进程 组 的 ID 

o timeout Number 毫秒 数 ， 子 进程 允许 运行 的 最 长 时 间 (R 
ik: undefined ) 

o killSignal String 结束 信号 (默认 : 'SIGTERM') 

o maxBuffer Number 在 stdout 或 stderr 中 允许 存在 的 最 大 缓冲 〈 二 进 制 ) ， 
如 果 超 出 那么 子 进程 将 会 被 杀 死 

o encoding String 被 用 于 所 有 stdio 输入 和 输出 的 编码 (默认 : 'buffer') 

e return: Object 


o pid Number F Æ 424) PID 

o output Array stdio 输出 结果 的 数组 

o stdout Buffer|String 子 进程 stdout 的 内 容 

o stderr Buffer|String 子 进 程 stderr HAR 

o status Number 子 进程 的 退出 码 

o signal String 被 用 于 杀 死 自 进程 的 信号 

o error Error 若 子 进程 运行 失败 或 超时 ， 它 将 会 是 对 应 的 错误 对 象 


spawnSync 会 在 子 进程 完全 结束 后 才 返 回 。 当 运行 超时 或 被 传 
% killSignal 时 ， 这 个 方法 会 等 到 进程 完全 退出 才 返 回 。 也 就 是 说 ， 如 果子 进 
程 处 理 了 SIGTERM 信号 并 且 没 有 退出 ， 你 的 父 进程 会 继续 阻塞 。 


child_process.execFileSync(command[, args][, options]) 


e command String 将 要 运行 的 命令 
e args Array 字符 串 参 数 数组 


e options Object 


o cwd String 子 进 程 的 当前 工作 目录 

o input String|Buffer 将 要 被 作为 stdin 传 入 被 创建 的 进程 的 值 ， 提 供 这 个 
WASH & stdio[0] 

o stdio Array 子 进程 的 stdio 配置 (默认: 'pipe') > stderr 默认 得 将 会 
输出 到 父 进程 的 stderr ， 除 非 指定 了 stdio 

o env Object 环境 变量 键 值 对 

o Uid Number 设置 用 户 进 程 的 ID 


o gid Number 设置 进程 组 的 ID 

o timeout Number 毫秒 数 ， 子 进程 允许 运行 的 最 长 时 间 〈 黑 
ik: undefined ) 

o killSignal 结束 信号 (默认 : 'SIGTERM') 

o maxBuffer Number 在 stdout 或 stderr 中 允许 存在 的 最 大 缓冲 〈 二 进 制 ) ， 
如 果 超 出 那么 子 进程 将 会 被 杀 死 

o encoding String 被 用 于 所 有 stdio 输入 和 输出 的 编码 (默认 : 'buffer') 

e return: Buffer|String 此 命令 的 stdout 


execFileSync 会 在 子 进 程 完全 结束 后 才 返 回 。 当 运行 超时 或 被 传 
递 killSignal 时 ， 这 个 方法 会 等 到 进程 完全 退出 才 返 回 。 也 就 是 说 ， 如 果子 进 
程 处 理 了 SIGTERM 信号 并 且 没 有 退出 ， 你 的 父 进 程 会 继续 阻塞 。 


如 果子 进程 超时 或 有 一 个 非 零 的 状态 码 ， 这 个 方法 会 抛 出 一 个 错误 。 这 个 错误 对 象 
与 child_process.spawnSync 的 错误 对 象 相同 。 


child_process.execSync(command{[, options]) 
e command 将 要 运行 的 命令 
e options Object 


o cwd String 子 进 程 的 当前 工作 目录 

o input String|Buffer 将 要 被 作为 stdin 传 入 被 创建 的 进程 的 值 ， 提 供 这 个 
值 将 会 覆盖 stdio[0] 

o stdio Array 子 进 程 的 stdio 配置 (默认 :'pipe') > stderr 默认 得 将 会 
输出 到 父 进程 的 stderr ， 除 非 指定 了 stdio 

o env Object 环境 变量 键 值 对 

o uid Number 设置 用 户 进程 的 ID 

o gid Number 设置 进程 组 的 ID 

o timeout Number 毫秒 数 ， 子 进程 允许 运行 的 最 长 时 间 〈 黑 
ik: undefined ) 

o killSignal String 结束 信号 (默认 : 'SIGTERM') 

o maxBuffer Number 在 stdout 或 stderr 中 允许 存在 的 最 大 缓冲 〈 二 进 制 ) ， 
如 果 超 出 那么 子 进 程 将 会 被 杀 死 

o encoding String 被 用 于 所 有 stdio 输入 和 输出 的 编码 (默认 : ‘buffer’ ) 

e return: Buffer|String 此 命令 的 stdout 


execSync 会 在 子 进程 完全 结束 后 才 返 回 。 当 运行 超时 或 被 传 
递 killSignal 时 ， 这 个 方法 会 等 到 进程 完全 退出 才 返 回 。 也 就 是 说 ， 如 果子 进 
程 处 理 了 SIGTERM 信号 并 且 没 有 退出 ， 你 的 父 进程 会 继续 阻塞 。 


如 果子 进程 超时 或 有 一 个 非 零 的 状态 码 ， 这 个 方法 会 抛 出 一 个 错误 。 这 个 错误 对 象 
与 child_process.spawnSync 的 错误 对 象 相同 。 


Cluster 


稳定 度 : 2 - 稳定 


单个 的 node .js 实例 运行 在 单线 程 上 。 为 了 享受 多 核 系统 的 优势 ， 用 户 需 要 启动 
一 个 node.js 集群 来 处 理 负载 。 


cluster 模块 允许 你 方便 地 创建 共享 服务 器 端口 的 子 进程 : 


var cluster = require('cluster'); 
var http = require('http'); 
var numCPUs = require('os').cpus().length; 


if (cluster.isMaster) { 
// Fork workers. 
for (var i = 0; i < numCPUs; i++) { 
cluster.fork(); 


cluster.on('exit', function(worker, code, signal) { 
console.log('worker ' + worker.process.pid + ' died'); 
+); 
} else { 
// Workers can share any TCP connection 
// In this case its a HTTP server 
http.createServer(function(reg, res) { 
res.writeHead( 200); 
res.end("hello world\n"); 
}).listen(8000); 


启动 node.js 将 会 在 工作 线程 中 共享 8000 端 口 : 


% NODE_DEBUG=cluster iojs server.js 
23521,Master Worker 23524 online 
23521,Master Worker 23526 online 
23521,Master Worker 23523 online 
23521,Master Worker 23528 online 


这 个 特性 是 最 近 才 开发 的 ， 并 且 可 能 在 未 来 有 所 改变 。 请 试用 它 并 提供 反馈 。 


注意 ， 在 Windows 中 ， 在 工作 进程 中 建立 命名 管道 服务 器 目前 是 不 可 行 的 。 


工作 原理 


alee aces child_process.fork 方法 被 创建 ， 所 以 它们 可 以 与 父 进程 通过 |IPC 
管道 沟通 以 及 相互 传递 服务 器 句柄 。 


集群 模式 支持 两 种 分 配 传 入 连接 的 方式 。 


中 (并且 是 除了 Windows 平 台 外 默认 的 方式 ) 是 循环 式 。 主 进程 监听 一 个 端 
口 ， ie 车 接 ， 并 且 以 轮流 的 方式 分 配给 工作 进程 ， 并 且 以 一 些 内 建 机 制 来 避免 
一 个 工作 进程 过 载 。 


第 二 种 方式 是 ， 主 进程 建立 监听 socket 并 且 将 它 发 送 给 感 兴 趣 的 工作 进程 。 工 作 
进程 直接 接受 传 入 的 连接 。 


第 二 种 方式 理论 上 有 最 好 的 性 能 。 但 是 在 ， 操作 系 统 的 调度 不 可 预测 ， 分 配 


往往 十 分 不 平衡 。 负 载 曾 被 观察 到 8 个 进程 中 ， 超 过 70% 的 连接 结束 于 其 中 的 2 个 进 
FE o 
因为 server.listen() 将 大 部 分 工作 交 给 了 主 进程 ， 所 以 一 个 普通 


的 node.js 进程 和 一 个 集群 工作 进程 会 在 三 种 情况 下 有 所 区 别 : 


1. server.listen({fd: 7}) 因为 消息 被 传递 给 了 主 进程 ， 主 进程 的 文件 描述 
符 7 会 被 监听 ， 并 且 和 句柄 会 被 传递 给 工作 进程 而 不 是 监听 工作 进程 中 文件 描 
述 符 为 7 的 东西 。 


2: 人 明确 地 监听 句柄 ， 会 让 工作 进程 使 用 给 定 的 名 
顶 ， 而 不 是 与 主 进程 通信 。 如 果 工 作 进 程 已 经 有 了 此 猛 柄 ， 那 么 将 假设 你 知道 
你 在 做 什么 


3. server.listen(0) 通常 ， 这 会 导致 服务 器 监听 一 个 随机 端口 。 但 是 ， 在 集 
群 中 ， 每 次 调用 listen(o) 时 ， 每 一 个 工作 进程 会 收 到 同样 的 “随机 ?端口 。 
也 就 是 说 ， 端 口 只 是 在 第 一 次 方法 被 调用 时 是 随机 的 ， 但 在 之 后 是 可 预知 的 。 
如 果 你 想 监 听 特 定 的 端口 ， 则 根据 工作 进程 的 PID 来 生成 端口 号 。 


由 于 在 node.js 或 你 的 程序 中 的 工作 进程 间 没 有 路 由 逻辑 也 没有 共享 的 状态 。 所 
以 ， 请 不 要 为 你 的 程序 设计 成 依赖 太 重 的 内 存 数据 对 象 ， 如 设计 会 话 和 登陆 时 。 


因为 工作 进程 都 是 独立 的 进程 ， 它 们 可 以 根据 你 程序 的 、 et | 建 ， 并 且 
并 不 会 影响 到 其 他 工作 进程 。 只 要 有 活跃 的 工作 进程 ， 那 么 器 就 会 继续 接收 连 
接 。 但 是 node.js 不 会 自动 地 为 你 管理 工作 进程 数 。 o 
理工 作 进 程 池 是 你 的 责任 。 


clusterschedulingPolicy 


调度 策略 ， 选 择 cluster.SCHED RR 来 使 用 循环 式 ， 或 选 
择 cluster.SCHED_NONE 来 由 操作 系统 处 理 。 这 是 一 个 全 局 设 定 ， 并 且 在 你 第 一 
次 启动 了 一 个 工作 进程 或 调用 cluster.setupMaster() 方法 后 就 不 可 再 更 改 。 


SCHED_RR 是 除了 Windows 外 其 他 操作 系统 中 的 默认 值 。 一 旦 libuv 能 够 有 效 地 
分 配 IOCP 句 柄 并 且 没 有 巨大 的 性 能 损失 ， 那 么 Windows 下 的 默认 值 也 会 变 为 它 。 


cluster.schedulingPolicy 也 可 以 通过 环境 变 


a 


量 NODE CLUSTER SCHED POLICY 来 设 定 。 合 法 值 为 rr 和 none 。 


cluster.settings 


e Object 

o execArgy Array 传递 给 node.js 执行 的 字符 串 参 数 (默认 
为 process.execArgv ) 

o exec String 工作 进程 文件 的 路 径 (SRILA process.argv[1] ) 

o args Array 传递 给 工作 进程 的 字符 串 参 数 (默认 
为 process.argv.slice(2) ) 

o silent Boolean 是 否 将 工作 进程 的 输出 传递 给 父 进程 的 stdio (RU 
为 false ) 

o Uid Number 设置 用 户 进程 的 ID 

o gid Number 设置 进程 组 的 ID 


在 调用 .setupMaster() (或 .fork() ) 方法 之 后 ， 这 个 settings 对 象 会 存 
放 方 法 的 配置 ， 包 括 默 认 值 。 


因为 ,setupMaster() 仅 能 被 调用 一 次 ， 所 以 这 个 对 象 被 设置 后 便 不 可 更 改 。 


这 个 对 象 不 应 由 你 来 手工 更 改 或 设置 。 


cluster.isMaster 

e Boolean 
如 果 进 程 是 主 进程 则 返回 true 。 这 由 process.env.NODE_UNIQUE_ID 决定 。 如 
果 process.env.NODE_UNIQUE_ID A undefined > MARAE true ° 
cluster.isWorker 

e Boolean 


如 果 进 程 不 是 主 进 程 则 返回 true 。 


Event: ‘fork’ 


e worker Worker object 


当 一 个 新 的 工作 进程 由 cluster 模块 所 开启 时 会 触发 fork 事件 。 这 能 被 用 来 记 
录 工 作 进 程 活动 日 志 ， 或 创建 自 定义 的 超时 。 


var timeouts = []; 
function errorMsg() { 
console.error("Something must be wrong with the connection ..." 
); 
} 


cluster.on('fork', function(worker) { 
timeouts[worker.id] = setTimeout(errorMsg, 2000); 


}); 
cluster.on('listening', function(worker, address) { 
clearTimeout(timeouts[worker.id]); 


}); 

cluster.on('exit', function(worker, code, signal) { 
clearTimeout(timeouts[worker.id]); 
errorMsg(); 


+); 
| a a 


Event: ‘online’ 


e worker Worker object 


当 创 建 了 一 个 新 的 工作 线程 后 ， 工 作 线 程 必 须 响 应 一 个 在 线 信 息 进程 接收 到 
在 线 信 息 后 它 会 触发 这 个 事件 。 fork 和 online ere > fork 是 主 
进程 创建 了 工作 进程 后 触发 ，online 是 工作 进程 开始 运行 时 触发 。 


cluster.on('online', function(worker) { 
console.log("Yay, the worker responded after it was forked"); 


+); 


Event: ‘listening’ 


e worker Worker object 
e address Object 


当 工 作 进程 调用 listen() 方法 。 服 务 器 会 触发 listening 事件 ， 集 群 中 的 主 进 
程 也 会 触发 一 个 listening 事件 。 


这 个 事件 的 回调 函数 包含 两 个 参数 ， 第 一 个 worker 是 一 个 包含 工作 进程 的 对 
象 ， address 对 象 是 一 个 包含 以 下 属性 的 对 

象 : address > port 和 addressType 。 当 工作 进程 监听 多 个 地 址 时 ， 这 非常 
有 用 。 


cluster.on('listening', function(worker, address) { 
console.log("A worker is now connected to " + address.address 
+ ":" + address.port); 


DO 


addressType 是 以 下 中 的 一 个 : 


e 4(TCPv4) 

e 6 (TCPV6) 

e -1 (unix domain socket) 

e "udp4" 或 "udp6" (UDP v4 或 v6) 


Event: ‘disconnect’ 


e worker Worker object 


当 工 作 进 程 的 |PC 信 道 断 开 连 接 时 触发 。 这 个 事件 当 工 作 进 程 优雅 地 退出 ， 被 杀 
死 ， 或 手工 断 开 连接 (如 调用 worker.disconnect() ) 后 触发 。 


disconnect 和 exit 事件 之 间 可 能 存在 延迟 。 这 两 个 事件 可 以 用 来 侦 测 是 否 进 
程 在 清理 的 过 程 中 被 阻塞 ， 或 者 是 否 存在 长 连接 。 


cluster.on('disconnect', function(worker) { 
console.log('The worker #' + worker.id + ' has disconnected'); 


3); 


Event: ‘exit' 


e worker Worker object 
e code Number 如 果 正 常 退出 ， 则 为 退出 码 
e signal String 导致 进程 被 杀 死 的 信号 的 信号 名 (4e'SIGHUP') 


当 任 何 一 个 工作 进程 结束 时 ， cluster 模块 会 触发 一 个 exit 事件 。 


这 可 以 被 用 来 通过 再 次 调用 .fork() 方法 重启 服务 器 。 


cluster.on('exit', function(worker, code, signal) { 


console.log('worker %d died (%s). restarting...', 
worker.process.pid, signal || code); 
cluster.fork(); 
+); 


参阅 child_process #4: exit 。 


Event: ‘setup’ 
e settings Object 
每 次 .setupMaster() 方法 被 调用 时 触发 。 


这 个 settings 对 象 与 .setupMaster() 被 调用 时 cluster.settings 对 象 相 
同 ， 并 且 仅 供 查询 ， 因 为 .setupMaster() 可 能 在 一 次 事件 循环 里 被 调用 多 次 。 


如 果 保 持 精 确 十 分 重要 ， 请 使 用 cluster.settings ° 


cluster.setupMaster([settings]) 


e settings Object 
o exec String 工作 进程 文件 的 路 径 (SRILA process.argv[1] ) 
o args Array 传递 给 工作 进程 的 参数 字符 串 (默认 
为 process.argv.slice(2) ) 
o silent Boolean 是 否 将 工作 进程 的 输出 传递 给 父 进程 的 stdio (默认 
为 false ) 


setupMaster 方法 被 用 来 改变 默认 的 fork 行为 。 一 旦 被 调用 ， settings 参 
数 将 被 表现 为 cluster.settings 。 


VERE ， 


e 任何 settings 的 改变 仅 影响 之 后 的 .fork() 调用 ， 而 不 影响 已 经 运行 中 的 
工作 进 和 

。 工作 进 is 不 同 通过 .setupMaster() 来 设置 的 属性 是 传递 
给 .fork() 方法 的 env 参数 

e。 上 文中 的 参数 的 默认 值 仅 在 第 一 次 调用 时 被 应 用 ， 之 后 的 调用 的 默认 值 是 当 


前 cluster.setupMaster() 被 调用 时 的 值 。 
例子 : 
var cluster = require('cluster'); 
cluster.setupMaster({ 
exec: 'worker.js', 
args: ['--use', 'https'], 


Silent: true 
+); 
cluster.fork(); // https worker 
cluster.setupMaster({ 
args: ['--use', ‘'http'] 
+); 


cluster.fork(); // http worker 
这 只 能 被 主 进程 调用 。 


clusterfork([env]) 


e env Object 将 添加 到 工作 进程 环境 变量 的 键 值 对 
e return Worker object 


创建 一 个 新 的 工作 进程 。 


这 只 能 被 主 进程 调用 。 


clusterdisconnect([callback]) 
e callback Function 当 所 有 的 工作 进程 断 开 连 接 并 且 所 有 句柄 关闭 后 调用 
在 cluster.workers 中 的 每 一 个 工作 进程 中 调用 .disconnect() ° 


当 所 有 进程 断 开 连 接 ， 所 有 内 部 的 句柄 都 将 关闭 ， 如 果 没 有 其 他 的 事件 处 于 等 待 ， 
将 允许 主 进程 优雅 地 退出 。 


这 个 方法 接受 一 个 可 选 的 将 会 在 结束 时 触发 的 回调 函数 参数 。 


这 只 能 被 主 进 程 调用 。 


cluster.worker 


e Object 


当前 工作 进程 对 象 的 引用 。 对 于 主 进 程 不 可 用 。 


var cluster = require('cluster'); 


if (cluster.isMaster) { 
console.log('I am master'); 
cluster.fork(); 
cluster.fork(); 
} else if (cluster.isWorker) { 
console.log('I am worker #' + cluster.worker.id); 


cluster.workers 
e Object 


a HAE RMA RR VA id 字段 为 主键 。 这 使 得 遍历 所 
有 工作 进程 变 得 容易 。 仅 在 主 进程 中 可 用 。 


当 工 作 进 程 断 开 连接 或 退出 时 ， 它 会 从 cluster.workers 中 移 除 。 这 个 两 个 事件 
的 触发 顺序 不 能 被 提前 决定 。 但 是 ， 能 保证 的 是 ， 从 cluster.workers 移 除 一 定 
发 生 在 这 两 个 事件 触发 之 后 。 


// Go through all workers 
function eachworker(callback) { 
for (var id in cluster.workers) { 
callback(cluster.workers[id]); 


} 


eachWorker(function(worker) { 
worker.send('big announcement to all workers'); 


D 


想 要 跨越 通信 信道 来 得 到 一 个 工作 进程 的 引用 时 ， 使 用 工作 进程 的 唯一 id 能 简单 
找到 工作 进程 


程 。 


socket.on('data', function(id) { 
var worker = cluster.workers[id]/; 


3); 


Class: Worker 


Worker 对 象 包含 了 一 个 工作 进程 所 有 的 公开 信息 和 方法 。 在 主 进 程 中 它 可 以 通 


过 cluster.workers 取得 。 在 工作 进程 中 它 可 以 通过 cluster.worker 取得 。 


Worker.id 


e String 


每 一 个 新 的 工作 进程 都 被 给 予 一 个 独一无二 的 id， 这 个 id 被 存储 在 此 id 属性 中 。 


当 一 个 工作 进程 活跃 时 ， 这 是 它 被 索引 在 cluster.workers 中 的 主键 。 


worker.process 
e ChildProcess object 


所 有 的 工作 进程 都 通过 ~Child_process.fork() 被 创建 ， 返 回 的 对 象 被 作 
为 .process 属性 存储 。 在 一 个 工作 进程 中 ， 全 局 的 process 被 存储 。 


参阅 Child Process module 
注意 ， 如 果 在 进程 中 disconnect 事件 触发 并 且 ,suicide 属性 不 为 true 
么 进程 会 调用 process.exit(0) 。 这 防止 了 意外 的 断 开 连接 。 
workersuicide 
e Boolean 
通过 调用 .kil1() 或 .disconnect() 设置 ， 在 这 之 前 他 为 undefined ° 


布尔 值 worker.suicide 使 你 可 以 区 别 自发 和 意外 的 退出 ， 主 进程 可 以 通过 
值 来 决定 使 用 重新 创建 一 个 工作 进程 。 


> Ap 


二 这 个 


cluster.on('exit', function(worker, code, signal) { 


if (worker.suicide === true) { 
console.log('Oh, it was just suicide\' - no need to worry'). 
} 
}); 


// kill worker 
worker.kill(); 


worker.send(message[, sendHandle]) 


e message Object 
e sendHandle Handle object 


给 工作 进程 或 主 进程 发 生 一 个 信息 ， 可 选 得 添加 一 个 句柄 。 
在 主 进 程 中 它 将 给 特定 的 工作 进程 发 送 一 个 信息 。 它 指向 child.send() 。 
在 工作 进程 中 它 将 给 主 进程 发 送 一 个 信息 。 它 指向 process.send() ° 
下 面 的 例子 将 来 自主 进程 的 所 有 信息 返回 : 
if (cluster.isMaster) { 


var worker = cluster.fork(); 
worker.send('hi there'); 


} else if (cluster.isWorker) { 
process.on('message', function(msg) { 
process.send(msg); 


}); 


worker.kill([signal='SIGTERM']) 
e signal String 传递 给 工作 进程 的 结束 信号 名 


这 个 函数 将 会 杀 死 工作 进程 。 在 主 进程 中 ， 它 通过 断 开 worker.process 做 到 ， 
并 且 一 旦 断 开 ， 使 用 signal 杀 死 进程 。 在 工作 进程 中 ， 它 通过 断 开 信道 做 到 ， 然 
后 使 用 退出 码 9 退出 。 


会 导致 ,suicide 被 设置 。 
为 了 向 后 兼任 ， 这 个 方法 的 别名 是 worker .destroy() ° 


注意 在 工作 进程 中 ， process.kill() 存在 ， 但 它 不 是 这 个 函数 。 
是 process.kill(pid[, signal]) ° 


worker.disconnect() 


在 工作 进程 中 ， 这 个 函数 会 关闭 所 有 的 服务 器 ， 等 待 这 些 服 务 器 上 的 close ¥ 
件 ， 然 后 断 开 IPC 信 道 。 


在 主 进程 中 ， 一 个 内 部 信息 会 被 传递 给 工作 进程 ， 至 使 它们 自行 调 


用 ,disconnect() ° 
会 导致 .suicide 被 设置 。 


注意 在 一 个 服务 器 被 关闭 后 ， 它 将 不 会 再 接受 新 连接 ， 但 是 连接 可 能 被 其 他 正在 监 
听 的 工作 进程 所 接收 。 已 存在 的 连接 将 会 被 允许 向 往常 一 样 退出 。 当 没有 更 多 的 连 
接 存在 时 ， 工 作 进 程 的 IPC 信 道 会 关闭 并 使 之 优雅 地 退出 ， 参 


阅 server.close() ° 


以 上 说 明 仅 应 用 于 服务 器 连接 ， 客 户 端 连 接 将 不 会 自动 由 工作 进程 关闭 ， 并 且 在 退 
出 前 ， 不 会 等 到 连接 退出 。 


注意 在 工作 进程 中 ， process.disconnect 存在 ， 但 它 不 是 这 个 函数 。 


是 child.disconnect() 。 


由 于 长 连接 可 能 会 阻塞 工作 进程 的 退出 ， 这 时 传递 一 个 动作 信息 非常 有 用 ， 应 用 来 
根据 信息 指定 的 动作 来 关闭 它们 。 超 时 机 制 是 上 述 的 有 用 实现 
在 disconnect 事件 在 指定 时 长 后 没有 触发 时 ， 杀 死 工 作 进 程 。 


if (cluster.isMaster) { 
var worker = cluster.fork(); 
var timeout; 


worker.on('listening', function(address) { 
worker.send('shutdown' ); 
worker.disconnect(); 
timeout = setTimeout(function() { 
worker.kill(); 
V200) 
}); 


worker.on('disconnect', function() { 
clearTimeout (timeout); 


+); 


} else if (cluster.isWorker) { 
var net = require('net'); 
var server = net.createServer(function(socket) { 
// connections never end 


}); 


server.listen(8000); 


process.on('message', function(msg) { 
if(msg === 'shutdown') { 
// initiate graceful close of any connections to server 
} 
}); 


worker.isDead() 


如 果 工 作 进 程 已 经 被 关闭 ， 则 返回 true 。 


worker.isConnected() 


如 果 工 作 进程 通过 它 的 |PC 信 道 连接 到 主 进 程 ， 则 返回 true 。 一 个 工作 进程 在 被 
创建 后 连接 到 它 的 主 进程 。 在 disconnect 事件 触发 后 它 会 断 开 连接 。 


Event: 'message' 

e message Object 
这 个 事件 与 child_process.fork() 所 提供 的 事件 完全 相同 。 
在 工作 进程 中 你 也 可 以 使 用 process.on('message') ° 


例子 ， 这 里 有 一 个 集群 ， 使 用 消息 系统 在 主 进程 中 统计 请 求 的 数量 : 


var cluster = require('cluster'); 
var http = require('http'); 


if (cluster.isMaster) { 


// Keep track of http requests 

var numReqs = 0; 

setInterval(function() { 
console.log("numReqgs =", numReqs); 

}, 1000); 


// Count requestes 
function messageHandler(msg) { 
if (msg.cmd && msg.cmd == 'notifyRequest') { 
numReqs += 1; 


// Start workers and listen for messages containing notifyRequ 
est 
var numCPUs = require('os').cpus().length; 
for (var i = 0; i < numCPUs; i++) { 
cluster.fork(); 


Object.keys(cluster.workers).forEach(function(id) { 
cluster.workers[id].on('message', messageHandler); 


+); 


} else { 


// Worker processes have a http server. 
http.Server(function(req, res) { 
res.writeHead( 200); 
res.end("hello world\n"); 


// notify master about the request 
process.send({ cmd: 'notifyRequest' }); 
}).listen(8000) ; 


Event: ‘online’ 


5 cluster.on('online') 事件 相似 ， 但 指向 了 特定 的 工作 进程 。 


cluster.fork().on('online', function() { 
// Worker is online 


}); 
这 不 是 在 工作 进程 中 触发 的 。 


Event: "listening' 
e address Object 


5 cluster.on('listening') 事件 相似 ， 但 指向 了 特定 的 工作 进程 。 


cluster.fork().on('listening', function(address) { 
// Worker is listening 


}); 
这 不 是 在 工作 进程 中 触发 的 。 


Event: 'disconnect' 


5 cluster.on('disconnect') 事件 相似 ， 但 指向 了 特定 的 工作 进程 


o 


cluster.fork().on('disconnect', function() { 
// Worker has disconnected 


}); 


Event: ‘exit' 


e code Number 如 果 正 常 退出 ， 则 为 退出 码 
e signal String 导致 进程 被 杀 死 的 信号 名 (如 'SIGHUP' ) 


与 cluster.on('exit') 事件 相似 ， 但 指向 了 特定 的 工作 进程 。 


var worker = cluster.fork(); 
worker.on('exit', function(code, signal) { 
if( signal ) { 
console.log("worker was killed by signal: "+signal); 


} else if( code !==0 ) { 
console.log("worker exited with error code: "+code); 
} else { 
console.log("worker success!"); 
} 
}); 


Event: 'error' 
这 个 事件 与 child_process.fork() 所 提供 的 事件 完全 相同 。 


在 工作 进程 中 你 也 可 以 使 用 process,on('error') 。 


Console 


稳定 度 : 2 - 稳定 
这 个 模块 定义 了 一 个 控制 台 类 ， 并 且 暴 露 了 一 个 console THe 


console 对 象 是 一 个 特殊 的 Console 实例 ， 它 的 输出 被 传 


至 stdout 或 stderr 。 


为 了 使 用 的 方便 ， console 被 定义 为 一 个 全 局 对 象 ， 不 需要 通过 require 就 可 
直接 使 用 。 
console 

e Object 


用 来 向 stdout 和 stderr 打印 信息 。 与 大 多 数 浏览 器 提供 的 console 对 象 的 功 
能 类 似 ， 只 是 这 里 输出 被 传 至 stdout 或 stderr ° 


当 目 的 地 是 终端 或 文件 时 (为 了 避免 过 早退 出 丢失 信息 ) ， console 函数 时 同步 
的 。 当 目的 地 是 管道 时 (为 了 避免 长 时 间 阻 塞 ) > console 函数 时 异步 的 。 


下 面 的 例子 里 ， stdout 是 非 阻塞 的 ，stderr 是 阻塞 的 : 


$ node script.js 2> error.log | tee info.log 


日 常 使 用 时 ， 除 了 你 需要 记录 大 量 数 量 的 数据 ， 你 不 用 担心 阻塞 / 非 阻塞 。 


console.log([data][, ...]) 


向 stdout 打印 一 行 新 信息 。 这 个 函数 可 以 像 printf() 那样 接受 多 个 参数 ， 例 


var count = 5; 
console.log('count: %d', count); 
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如 果 第 一 个 字符 串 中 没有 发 现 格式 化 元 素 ， 那 么 util.inspect 将 被 应 用 到 各 个 
参数 。 详 情 参 阅 util.format() ° 
console.info([{data][, ...]) 


5 console.log 相同 。 


console.error([data][, ...]) 


4 console.log 相同 。 但 是 输出 至 stderr 。 


console.warn([datall, ...]) 


与 console.err 相同 。 


console.dir(obj[, options]) 


对 obj 调用 util.inspect 并 且 将 结果 字符 串 输出 至 stdout 。 这 个 函数 会 急 
略 obj 上 的 任何 自 定 义 inspect() 有 函数 。 一 个 可 选 的 options 参数 可 以 被 传递 
用 来 格式 化 字符 串 的 某 些 方面 : 


e showHidden - 如 果 为 true > object 的 不 可 枚 举 和 标志 属性 也 会 被 显示 。 
默认 为 false ° 


e depth - 告诉 inspect 在 格式 化 对 象 时 递 具 多 少 次 。 在 检查 大 而 复杂 的 对 象 时 
很 有 有 用。 默认 为 2。 若 要 递归 到 底 则 传递 null 。 


e colors - 如 果 为 true ， 那 么 输出 会 以 ANSI 颜 色 码 的 形式 输出 。 默 认 
为 false 。 闫 色 是 可 以 自 定义 ， 参 阅 下 文 。 
console.time(label) 


被 用 来 计算 指定 操作 之 间 时 间 间 隔 。 为 了 开始 一 个 timer ， 调 
用 console.time() 方法 ， 作 为 唯一 参数 可 以 给 它 一 个 名 字 。 为 了 关闭 一 
个 timer ， 并 且 得 到 上 毫秒 间隔 ， 仅 仅 以 相同 的 名 字 参 数 调用 一 


次 console.timeEnd() ° 


console.timeEnd(label) 


停止 一 个 之 前 通过 console.time() 开启 的 timer ， 并 且 向 控制 台 打 印 结 果 。 


例子 : 


console.time('100-elements'); 

for (var i= 0 i < 100; irt) f 
/ 

} 

console.timeEnd('100-elements'); 

/7 prants 100-elements: 262ms 


console.trace(message[, ...]) 


stderr 打印 'Trace :' ， 跟 随 着 格式 化 信息 和 堆栈 信息 。 


console.assert(value[, message], ...]) 


与 assert.ok() 类 似 ， 但 是 错误 信息 被 像 util.format(message...) 一 样 格 式 
化 。 

Class: Console 

使 用 require('console') 后 。 Console 或 console.Console 可 以 取得 这 个 


类 。 


var Console = require('console').Console; 
var Console = console.Console; 


你 可 以 调用 Console 类 来 自 定 义 如 console 一 样 的 简单 日 记 记 录 器 ， 但 是 有 不 
同 的 输 出 流 


new Console(stdout[, stderr]) 


通过 传递 一 个 或 两 个 可 写 流 实例 ， 创 建 一 个 新 的 Console 。 stdout 是 一 个 用 来 
打印 日 志和 信息 的 输出 流 。 stderr 是 一 个 被 用 来 打印 警告 和 错误 输出 的 。 如 
果 stderr er. 那么 警告 和 错误 信息 将 被 传递 至 stdout ° 


var output = fs.createWriteStream('./stdout.log'); 

var errorOutput = fs.createwWriteStream('./stderr.log'); 
// custom simple logger 

var logger = new Console(output, errorOutput); 

// use it like console 

var count = 5; 

logger.log('count: %d', count); 

i7 Ane Seaoue.L0g: count. 5 


全 局 的 console 是 一 个 特殊 的 Console 实例 ， 它 的 输出 被 传递 


至 process.stdout 和 process.stderr 


new Console(process.stdout, process.stderr); 


Crypto 


稳定 度 :2 - 稳定 
使 用 require('crypto') 来 获取 这 个 模块 。 


crypto 模块 提供 了 一 种 封装 安全 证 书 的 方法 ， 用 来 作为 安全 HTTPS 网 络 和 HTTP 
链接 的 一 部 分 。 


它 也 提供 了 一 个 OpenSSL 

hash ， hamc ， cipher ， decipher ， sign 和 vierify 方法 的 包装 集 
要 

a 


crypto.setEngine(engine[, flags]) 
加 载 和 设置 一 些 /所 有 OpenSSL 功 能 引擎 〈 由 标记 选择 ) 。 
引擎 可 以 通过 id 或 引擎 共享 库 的 路 径 来 选择 。 


flags 是 可 选 的 ， 并 且 有 一 个 ENGINE_METHOD_ALL 默认 值 。 可 以 选 一 个 或 多 个 
以 下 的 标记 (在 常量 模块 中 定义 ) 。 


e ENGINE_METHOD_RSA 
e ENGINE_METHOD_DSA 

e ENGINE_METHOD_DH 

e ENGINE_METHOD_RAND 

e ENGINE_METHOD_ECDH 

e ENGINE_METHOD_ECDSA 

e ENGINE_METHOD_CIPHERS 

e ENGINE_METHOD_DIGESTS 

e ENGINE_METHOD_STORE 

e ENGINE_METHOD_PKEY_METH 

e ENGINE_METHOD_PKEY_ASN1_METH 
e ENGINE_METHOD_ALL 

。ENGINE METHOD NONE 


crypto.getCiphers() 


返回 一 个 支持 的 加 密 算法 的 名 字数 组 。 


例子 : 


var ciphers = crypto.getCiphers(); 
console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...] 


crypto.getHashes() 
返回 一 个 支持 的 哈 希 算法 的 名 字数 组 。 


例子 : 


var hashes = crypto.getHashes(); 
console.log(hashes); // ['sha', 'shai', 'shaiWithRSAEncryption', 


vod 
crypto.getCurves() 
返回 一 个 支持 的 椭圆 加 密 算 法 的 名 字数 组 。 
例子 : 


var curves = crypto.getCurves(); 
console.log(curves); // ['secp256k1', 'secp384r1', ...] 


crypto.createCredentials(details) 
稳定 度 : 0 - 弃 用 。 使 用 tls.createSecureContext 代替 。 
创建 一 个 加 密 赁 证 对 象 ， 接 受 一 个 可 选 的 带 键 字典 details 


e pix: 一 个 带 着 PFX 或 PKCS12 加 密 的 私 钥 ， 加 密 赁 证 和 CA 证 书 的 字符 串 
或 buffer ° 

e key: 一 个 带 着 PEM 加 密 私 钥 的 字符 串 。 

e passphrase : 一 个 私 钥 或 pfx 密码 字符 串 。 

e cert: 一 个 带 着 PEM 加 密 赁 证 的 字符 串 。 

。 ca: 一 个 用 来 信任 的 PEM 加 密 CA 证 书 的 字符 串 或 字符 串 列表 。 


e crl : 一 个 PEM 加 密 CRL 的 字符 串 或 字符 串 列 表 。 

e ciphers: 一 个 描述 需要 使 用 或 排除 的 加 密 算 法 的 字符 事 。 更 多 加 密 算 法 的 格式 
细节 参 
X] http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FOR 
MAT 


如 果 没 有 指定 ca ， 那 么 node.js 将 会 使 
用 http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/built 
ins/certdata.txt. 提供 的 默认 公共 可 信任 CA 列表 。 


crypto.createHash(algorithm) 
创建 并 返回 一 个 哈 布 对 象 ， 一 个 指定 站 法 的 加 蜜 哈 希 用 来 生成 哈 布 摘要 。 


algorithm 依赖 于 平台 上 的 OpenSSL 版 本 所 支持 的 算法 。 例 


如 'shai' > 'md5' ° 'sha256' > 'sha512' +-=F ° openssl list- 
message-digest-algorithms 命令 会 展示 可 用 的 摘要 算法 。 


例子 : 这 个 程序 计算 出 一 个 文件 的 sha1 摘 要 : 


var filename = process.argv[2]; 
var crypto = require('crypto'); 
Var is = require as"); 


var shasum = crypto.createHash('shai'); 


var s = fs.ReadStream( filename) ; 
s.on('data', function(d) { 
shasum.update(d); 


} yp 


s.on('end', function() { 
var d = shasum.digest('hex'); 
console.log(d + ' ' + filename); 


}); 


Class: Hash 


这 个 类 用 来 创建 数据 哈 希 摘要 。 


这 是 一 个 同时 可 读 与 可 写 的 流 。 写 入 的 数据 用 来 计算 哈 希 。 一 旦 当 流 的 可 写 端 终 
止 ， 使 用 read() 来 获取 计算 所 得 哈 布 摘 要 。 遗 留 的 update 和 digest 方法 同 
样 被 支持 。 


通过 crypto.createHash 返回 。 


hash.update(data[, input encoding]) 


使 用 给 定 的 data 更 新 哈 希 内 容 ， 通 过 input encoding 指定 的 编码 可 以 


日 


是 ‘utf8' > 'ascii' 或 'binary' 。 如 果 没 有 提供 编码 ， 并 且 输 入 是 一 个 字符 
串 ， 那 么 将 会 指定 编码 为 'binary' 。 如 果 data 是 一 个 Buffer 那 
么 input_encoding 会 被 忽略 。 


它 是 流 式 数据 ， 所 以 这 个 方法 可 以 被 调用 多 次 。 


hash.digest([encoding]) 


计算 所 有 的 被 传递 的 数据 的 摘要 。 encoding 可 以 
是 'binary' > 'hex' 或 'base64' 。 如 果 没 有 指定 编码 ， 那 么 一 
个 buffer 被 返回 。 


注意 : 当 调 用 了 digest() 方法 之 后 ， 哈 希 对 象 不 能 再 被 使 用 了 。 


crypto.createHmac(algorithm, key) 


创建 并 返回 一 个 hmac 对 象 ， 即 通过 给 定 的 算法 和 密 钥 生成 的 加 密 图 谱 
(cryptographic) ° 


这 是 一 个 既 可 读 又 可 写 的 流 。 写 入 的 数据 被 用 来 计算 hamc。 一 旦 当 流 的 可 写 端 终 
止 ， 使 用 read() 方法 来 获取 计算 所 得 摘要 值 。 遗 留 的 update 和 digest 方法 
同样 被 支持 。 


algorithm 依赖 于 平台 上 的 OpenSSL 版 本 所 支持 的 算法 。 参 阅 上 
X createHash 。 key 是 要 使 用 的 hmac 密 钥 。 

Class: Hmac 

用 于 创建 hmac 加 密 图 谱 (cryptographic) 的 类 。 


通过 crypto.createHmac 返回 。 


hmac.update(data) 


只 用 指定 的 data 更 新 hmac 内 容 。 因 为 它 是 流 式 数据 ， 所 以 这 个 方法 可 以 被 调用 


多 次 。 


hmac.digest([encoding]) 


计算 所 有 的 被 传递 的 数据 的 hmac 摘 要 。 encoding 可 以 
是 'binary' ° 'hex' 或 'base64' 。 如 果 没 有 指定 编码 ， 那 么 一 
个 buffer 被 返回 。 


注意 : 当 调 用 了 digest() 方法 之 后 ，hmac 对 象 不 能 再 被 使 用 了 。 


crypto.createCipher(algorithm, password) 
创建 和 返回 一 个 cipher 对 象 ， 指 定 指定 的 算法 和 密码 。 


算法 依赖 于 OpenSSL， 如 果 'aesi92' ， 等 等 。 在 最 近 的 发 行 版 中 ， openssl 
list-cipher-algorithms 命令 会 展示 可 用 的 cipher 算法 。 密 码 被 用 来 获取 密 
钥 和 |IV， 必 须 是 一 个 'binary' 编码 的 字符 串 或 buffer ° 


这 是 一 个 既 可 读 又 可 写 的 流 。 写 入 的 数据 被 用 来 计算 哈 希 。 一 旦 当 流 的 可 写 端 终 
止 ， 使 用 read() 方法 来 获取 通过 cipher 计算 所 得 的 内 容 。 遗 留 
的 update 和 digest 方法 同样 被 支持 。 


注意 : createCipher 通过 £2 MD5 一 次 迭代 所 得 的 摘要 来 调用 0penSSL 函 
数 EVP_BytesToKey 来 派生 密 钥 。 无 盐 意 味 允 许字 典 攻击 ， 即 同样 的 密码 经 常 可 
以 用 来 创建 同样 的 密 钥 。 一 次 近代 并 且 无 加 密 图 谱 安 全 (non-cryptographically 
secure) 以 为 着 允许 密码 被 快速 测试 。 


OpenSSL 建 议 使 用 pbkdf2 替代 EVP_BytesToKey ， 推 荐 你 通 

过 crypto.pbkdf2 然后 调用 createCipheriv() 创建 一 个 cipher 流 来 派生 一 
个 蜜 钥 和 iv。 

crypto.createCipheriv(algorithm, key, iv) 

创建 和 返回 一 个 cipher 对 和 象 ， 指 定 指定 的 算法 ， 密 钥 和 iv。 


algorithm #24 createCipher() 相同 。 key 是 被 算法 使 用 的 源 密 钥 (raw 
key) 。iv 是 初始 化 矢量 (initialization vector) ° 


key 和 iv 必须 是 'binary' 编码 的 字符 串 或 buffer 。 


Class: Cipher 
创建 一 个 加 密 数 据 。 
由 crypto.createCipher 和 crypto.createCipheriv 返回 。 


这 是 一 个 既 可 读 又 可 写 的 流 。 写 入 的 文本 数据 被 用 来 在 可 读 端 生产 被 加 蜜 的 数据 。 
sate 


日 
遗留 的 update 和 final 方法 同样 被 支持 。 


cipher.update(data[, input_encoding][, output_encoding]) 


通过 data 更 新 cipher > input_encoding 中 指定 的 编码 可 以 
是 'utf8' > 'ascii' 或 'binary' 。 如 果 没 有 提供 编码 ， 那 么 希望 接受 到 一 
buffer 。 如 果 数 据 是 一 个 Buffer > PRA input_encoding 将 被 忽略 。 


output_encoding 指定 了 加 蜜 数据 的 输出 格式 ， 可 以 
是 'binary' ， 'base64' 或 'hex' 。 如 果 没 有 指定 编码 ， 那 么 一 
个 buffer 会 被 返回 。 


返回 一 个 加 密 内 容 ， 并 且 因 为 它 是 流 式 数据 ， 所 以 可 以 被 调用 多 次 。 


cipher.final([output_encoding]) 


返回 所 有 的 剩余 的 加 密 内 容 ， output_encoding 可 以 
Æ 'binary' > 'base64' 或 'hex' 。 如 果 没 有 指定 编码 ， 那 么 一 
个 buffer 会 被 返回 。 


注意 : 当 调 用 了 final() 方法 之 后 ，cipher 对 象 不 能 再 被 使 用 了 。 


cipher.setAutoPadding(auto_padding=true) 


你 可 以 禁用 自动 填充 输入 数据 至 块 大 小 。 如 果 auto_padding 为 false ， 那 么 整 
个 输入 数据 的 长 度 必 须 cipher 的 块 大 小 的 整数 倍 ， 否 则 会 失败 。 这 对 非 标 准 填充 
非常 有 用 ， 如 使 用 0x0 替 代 PKCS 卉 充 。 你 必须 在 cipher ,final 之 前 调用 它 。 


cipher.getAuthTag() 


对 于 已 认证 加 密 模 式 (当前 支持 : GCM) ， 这 个 方法 返回 一 个 从 给 定数 据 计 算 所 得 
的 代表 了 认证 标签 的 Buffer 。 必 须 在 final 方法 被 调用 后 调用 。 
cipher.setAAD(buffer) 

对 于 已 认证 加 密 模 式 (当前 支持 : GCM) ， 这 个 方法 设置 被 用 于 额外 已 认证 数据 
(AAD) 输入 参数 的 值 。 

crypto.createDecipher(algorithm, password) 

18 Le eK Ae BA > CHIR — SABE MR o RE 

X createCipher() 的 一 个 镜像 。 
crypto.createDecipheriv(algorithm, key, iv) 

使 用 给 定 葛 法 ， 密 铀 和 iv， 创 建 并 返回 一 个 解密 器 对 象 。 这 是 上 


文 createCipheriv() 的 一 个 镜像 。 


Class: Decipher 


通过 crypto.createDecipher 和 crypto.createDecipheriv 返回 。 


这 是 一 个 既 可 读 又 可 写 的 流 。 写 入 的 被 加 密 的 数据 被 用 来 在 可 读 端 生产 文本 数据 。 
遗留 的 update 和 final 方法 同样 被 支持 。 


decipherupdate(data[, input_encoding][, output_encoding]) 


通过 data 更 新 decipher ， 编 码 可 以 是 'binary' ， 'base64' 或 'hex' 。 
果 没 有 提供 编码 ， 那 么 希望 接受 到 一 个 buffer 。 如 果 数 据 是 一 个 Buffer ， 
那么 input_encoding 将 被 忽略 。 


output_encoding 指定 了 解密 数据 的 输出 格式 ， 可 以 
是 'binary' > 'ascii' 或 'utf8' 。 如 果 没 有 指定 编码 ， 那 么 一 
个 buffer 会 被 返回 。 


decipher.final([output_encoding]) 


返回 所 有 的 剩余 的 文本 数据 ， output_encoding 可 以 
是 'binary' > ‘ascii' 或 'utf8' 。 如 果 没 有 指定 编码 ， 那 么 一 
个 buffer 会 被 返回 。 


注意 : 当 调 用 了 final() 方法 之 后 ，decipher 对 象 不 能 再 被 使 用 了 。 


decipher.setAutoPadding(auto_padding=true) 

如 数据 没有 使 用 标准 块 填充 阻止 decipher.final 检查 和 删除 它 来 加 密 ， 你 可 以 
禁用 自动 填充 。 那 么 整个 输入 数据 的 长 度 必 须 cipher 的 块 大 小 的 整数 倍 ， 否 则 会 
失败 。 你 必须 在 将 数据 导 流 至 decipher.update 前 调用 它 。 
decipher.setAuthTag(buffer) 

对 于 AA (当前 支持 : GCM) ， 这 个 方法 必须 被 传递 ， 用 来 接受 认证 标 
签 。 如 果 没 有 提供 标签 或 密 文 被 干扰 ， 最 终 会 抛 出 一 个 错误 。 
decipher.setAAD(buffer) 

对 于 已 认证 加 密 模 式 (当前 支持 : GCM) ， 这 个 方法 设置 被 用 于 额外 已 认证 数据 
(AAD) 输入 参数 的 值 。 

crypto.createSign(algorithm) 

使 用 指定 的 算法 ， 创 建 并 返回 一 个 数字 签名 类 。 在 最 近 的 OpenSSL 发 行 版 

中 ， openssl list-public-key-algorithms 会 列 出 所 有 支持 的 数字 签名 算法 。 
例如 'RSA-SHA256' ° 

Class: Sign 

用 于 生成 数字 签名 的 类 。 

通过 crypto.createSign 返回 。 

Sign 对 象 是 一 个 可 写 流 。 写 入 的 数据 用 来 生成 数字 签名 。 一 旦 所 有 的 数据 被 写 
A? sign 方法 会 返回 一 个 数字 签名 。 遗 留 的 update 方法 也 支持 。 
sign.update(data) 


使 用 data 更 新 sign 对 象 。 因 为 它 是 流 式 的 所 以 这 个 方法 可 以 被 调用 多 次 。 


sign.sign(private_key[, output_format]) 
根据 所 有 通过 update 方法 传 入 的 数据 计算 数字 签名 。 


private_key 可 以 是 一 个 对 象 或 一 个 字符 串 ， 如 果 private_key 是 一 个 字符 
串 ， 那 么 它 被 当做 没有 密码 的 密 钥 。 


private_key: 


。 key: 包含 PEM 编码 私 铀 的 字符 串 。 
e passphrase : 一 个 私 钥 密码 的 字符 串 。 


返回 的 数字 签名 编码 由 output_format 决定 ， 可 以 
是 'binary' > 'hex! 或 'base64' 。 如 果 没 有 指定 编码 会 返回 一 
个 buffer 。 


注意 ， 在 调用 了 sign() 后 ， sign 对 象 不 能 再 使 用 了 ° 


crypto.createVerify(algorithm) 


使 用 给 定 的 算法 ， 创 建 并 返回 一 个 验证 器 对 象 。 这 个 对 象 是 sign 对 象 的 镜像 。 


Class: Verify 
用 来 验证 数字 签名 的 类 。 
由 crypto.createVerify 返回 。 
Verify 对 象 是 一 个 可 写 流 。 写 入 的 数据 用 来 验证 提供 的 数字 签名 。 一 旦 所 有 的 数 
据 被 写 入 ， verify 方法 会 返回 true 如果 提供 的 数字 签名 有 效 。 遗 留 
的 update 方法 也 支持 。 
verifier.update(data) 
使 用 data 更 新 verifier 对 象 。 因 为 它 是 流 式 的 所 以 这 个 方法 可 以 被 调用 多 


Ro 


verifier.verify(object, signature[, signature_format)]) 


通过 使 用 object 和 signature 验证 被 签名 的 数据 。 object 是 一 个 包含 了 
PEM 编 码 对 象 的 字符 串 ， 这 个 对 象 可 以 是 RSA 公 铀 ，DSA 公 铀 或 X.509 证 

书 。 signature 是 先前 计算 出 来 的 数字 签名 ， signature_format 可 以 

Æ 'binary' > 'hex' 或 'base64' 。 如 果 没 有 指定 编码 ， 那 么 希望 收 到 一 
个 buffer 。 


返回 值 是 true 或 false 根据 数字 签名 对 于 数据 和 公 和 钥 的 有 效 性 。 


注意 ， 在 调用 了 verify() Æ> verifier 对 象 不 能 再 使 用 了 。 


crypto.createDiffieHellman(prime_length[, generator]) 
创建 一 个 迪 菲 一 赫 尔 曼 密 钥 交换 对 象 (Diffie-Hellman key exchange object) ， 并 


且 根 据 prime_length 生成 一 个 质数 ， 可 以 指定 一 个 可 选 的 数字 生成 器 。 如 果 没 
有 指定 生成 器 ， 将 使 用 2 © 


crypto.createDiffieHellman(prime[, prime_encoding]|[, 
generator][, generator_encoding}) 


通过 给 定 的 质数 ， 和 可 选 的 生成 器 ， 创 建 一 个 迪 菲 一 赫 尔 曼 密 铀 交换 对 象 (Diffie- 
Hellman key exchange object) 。 generator 可 以 是 一 个 数字 ， 字 符 事 

或 Buffer 。 如 果 没 有 指定 生成 器 ， 将 使 

用 2 。 prime_encoding 和 generator_encoding 可 以 

Æ 'binary' > 'hex' 或 'base64' 。 如 果 没 有 指定 prime_encoding ， 和 那么 
希望 prime 是 一 个 Buffer 。 如 果 没 有 指定 generator_encoding > MAA 


望 generator 是 一 个 Buffer 。 


Class: DiffieHellman 
叫 来 创建 迪 菲 一 赫 尔 曼 密 钥 交 换 的 类 。 


通过 crypto.createDiffieHellman 返回 。 


diffieHellman.verifyError 


一 个 包含 了 所 有 警告 和 /或 错误 的 位 域 ， 作 为 检查 初始 化 时 的 执行 结果 。 以 下 是 这 个 
属性 的 合法 属性 (被 常量 模块 定义 ) 


e DH _CHECK P_NOT SAFE PRIME 


e DH CHECK _P_NOT PRIME 
e DH _UNABLE_TO_CHECK_GENERATOR 
e DH NOT _SUITABLE_GENERATOR 


diffieHellman.generateKeys([encoding]) 


生成 一 个 AL Fa LS a JE — ah pe BR AR AB 9 并 且 返 回 一 个 指定 编码 的 公 铀 这 个 密 铀 
可 以 被 转移 给 第 三 方 。 编 码 可 以 是 'binary' > 'hex' 或 'base64' 。 如 果 没 有 
提供 编码 ， 那 么 会 返回 一 个 buffer ° 


diffieHellman.computeSecret(other_public_keyl|， 
input_encoding][, output_encoding]) 


上 大 大 ”一 


使 用 other_public_key 作为 第 三 方 蜜 钥 来 计算 共享 秘密 (shared secret) ， 并 
且 返 回 计 算 结 果 。 提 供 的 密 钥 会 以 input_encoding 来 解读 ， 并 且 秘 蜜 

以 output_encoding 来 编码 。 编 码 可 以 

是 'binary' > 'hex' 或 'base64' 。 如 果 没 有 提供 编码 ， 那 么 会 返回 一 

个 buffer 。 


如 果 没 有 指定 output_encoding ， 那 么 会 返回 一 个 buffer 。 


diffieHellman.getPrime([encoding]) 


ARGE 48 CY AY UR E — ah SE — tp OR SH > HART VA 
Æ 'binary' > 'hex' 或 'base64' 。 如 果 没 有 提供 编码 ， 那 么 会 返回 一 
个 buffer 。 


diffieHellman.getGenerator([encoding]) 


根据 指定 编码 返回 一 个 迪 菲 一 赫 尔 曼 生 成 器 ， 编 码 可 以 
Æ 'binary' ， 'hex' 或 'base64' 。 如 果 没 有 提供 编码 ， 那 么 会 返回 一 
个 buffer 。 


diffieHellman.getPublicKey([encoding]) 


根据 指定 编码 返回 一 个 迪 菲 一 本 尔 曼 公 钥 ， 编 码 可 以 
是 'binary' ， 'hex' 或 'base64' 。 如 果 没 有 提供 编码 ， 那 么 会 返回 一 
个 buffer 。 


diffieHellman.getPrivateKey([encoding]) 


根据 指定 编码 返回 一 个 迪 菲 一 赫 尔 曼 私 钥 ， 编 码 可 以 

是 'binary' > 'hex' 或 'base64' 。 如 果 没 有 提供 编码 ， 那 么 会 返回 一 

个 buffer 。 

diffieHellman.setPublicKey(public_key[, encoding]) 

设置 迪 菲 一 赫 尔 曼 公 钥 ， 密 钥 编 码 可 以 是 'binary' > 'hex' X 'base64' ° 4 
多 


Seer 编码 ， 那 么 期 望 接收 一 个 buffer 。 


diffieHellman.setPrivateKey(private_key[, encoding]) 


设置 迪 菲 一 赫 尔 曼 私 钥 ， 密 钥 编码 可 以 是 'binary' ， 'hex' 或 'base64' 。 如 
果 没 有 提供 编码 ， 那 么 期 望 接收 一 个 buffer 。 


crypto.getDiffieHellman(group_name) 


创建 一 个 预定 义 的 迪 菲 一 赫 尔 曼 密 钥 交换 对 象 。 支 持 的 群 组 有 : 'modpt', 'modp2’, 
'modp5' (由 RFC 2412 定 义 ) # 'modp14', 'modp15', 'modp16', 'modp17', 'modp18' 
(GRFC 3526 定 义 )。 返 回 的 对 象 模仿 crypto.createDiffieHellman() 创建 的 对 
象 的 借口 ， 但 是 不 允许 交换 密 钥 (如 通过 diffieHellman.setPublickey() ) ° 
执行 这 套 流 程 的 好 处 是 双方 不 需要 事先 生成 或 交换 组 余数 ， 节 省 了 处 理 和 通信 时 

间 。 


例子 (获取 一 个 共享 秘密) 


var crypto = require('crypto'); 
var alice = crypto.getDiffieHellman('modp5'); 
var bob = crypto.getDiffieHellman('modp5'); 


alice.generateKeys(); 
bob.generateKeys(); 


var alice_secret = alice.computeSecret(bob.getPublicKey(), null, 
"hex'); 
var bob_secret = bob.computeSecret(alice.getPublicKey(), null, ' 
hex'); 


/* alice_secret and bob _secret should be the same */ 


console.log(alice_secret == bob_secret); 


OE” I 
crypto.createECDH(curve_name) 


使 用 由 curve_name 44 ZA EUA > e—a A R (EC) 迪 菲 一 赫 尔 曼 
密 钥 交换 对 象 。 使 用 getCurves() 来 获取 可 用 的 椭圆 名 列表 。 在 最 近 的 发 行 版 
P > openssl ecparam -list_curves 命令 也 会 展示 可 用 的 椭圆 曲线 的 名 字 和 简 
E 


Class: ECDH 


用 于 EC 过 菲 一 赫 尔 受 密 钥 交换 的 类 。 


由 crypto.createECDH 返回 。 


ECDH.generateKeys([encoding[, format]]) 


生成 一 个 私 / 公 EC 迪 菲 一 赫 尔 曼 密 钥 值 ， 并 且 返 回 指定 格式 和 编码 的 公 钥 。 这 个 蜜 
钥 可 以 被 转移 给 第 三 方 。 


format 指定 点 的 编码 ， 可 以 
a 


是 'compressed' > 'uncompressed' 或 'hybrid' 。 如 果 没 有 指定 ， 那 么 点 将 
是 'uncompressed' 格式 。 


编码 可 以 是 'binary' > 'hex' 或 'base64' 。 如 果 没 有 提供 编码 ， 那 么 会 返回 


一 个 buffer 。 


ECDH.computeSecret(other_public_key[, input_encoding][, 
output_encoding}) 


大 大 ”一 


使 用 other_public_key 作为 第 三 方 密 钥 来 计算 共享 秘密 (shared secret) ， 并 
且 返 回 计 算 结 果 。 提 供 的 密 钥 会 以 input_encoding 来 解读 ， 并 且 秘 密 

以 output_encoding 来 编码 。 编 码 可 以 

Æ 'binary' > 'hex' Ñ 'base64' 。 如 果 没 有 提供 编码 ， 那 么 会 返回 一 


个 buffer 。 


如 果 没 有 指定 output_encoding ， 那 么 会 返回 一 个 buffer 。 


ECDH.getPublicKey([encoding[, format]]) 
返回 指定 编码 和 格式 的 EC 迪 菲 一 赫 尔 概 公 铀 。 


format 指定 点 的 编码 ， 可 以 

Æ 'compressed' > 'uncompressed' 或 'hybrid' 。 如 果 没 有 指定 ， 那 么 点 将 
是 'uncompressed' 格式 。 

编码 可 以 是 'binary' > 'hex' 或 'base64' 。 如 果 没 有 提供 编码 ,那么 会 返回 


一 个 站 De e 


ECDH.getPrivateKey([encoding]) 


返回 指定 编码 的 EC 迪 养 一 赫 尔 曼 私 钥 ， 编 码 可 以 
Æ 'binary' ， 'hex' 或 'base64' 。 如 果 没 有 提供 编码 ， 那 么 会 返回 一 


个 buffer 。 


ECDH.setPublicKey(public_key[, encoding]) 


设置 EC 迪 菲 一 赫 和 尔 受 公 钥 。 密 钥 编码 可 以 
是 'binary' ， 'hex' 或 'base64' 。 如 果 没 有 提供 编码 ， 那 么 期 望 接收 一 


个 buffer 。 


ECDH.setPrivateKey(private_key[, encoding]) 
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Æ 'binary' > 'hex' 或 'base64' 。 如 果 没 有 提供 编码 ， 那 么 期 望 接收 一 
个 buffer 。 


例子 (获取 一 个 共享 秘密 ) 


var crypto = require('crypto'); 
var alice = crypto.createECDH( 'secp256k1'); 
var bob = crypto.createECDH('secp256k1'); 


alice.generateKeys(); 
bob.generateKeys(); 


var alice_secret = alice.computeSecret(bob.getPublicKkey(), null, 
"hex'); 

var bob_secret = bob.computeSecret(alice.getPublicKey(), null, ' 
hex'); 


/* alice secret and bob secret should be the same */ 
console.log(alice_secret == bob_secret); 


E | 


crypto.pbkdf2(password, salt, iterations, keylen[, digest], 
callback) 


A Y PBKDF2 Hak © HEHE AR EE HAMC BHA (RIUASHA1) 来 获取 一 个 请 
求 长 度 的 密码 密 钥 ， 盐 和 和 迭代 数 。 回 调 函 数 有 两 个 参数 : 


( err > derivedkey ) ° 


例子 : 


crypto.pbkdf2('secret', ‘salt', 4096, 512, 'sha256', function(er 
r, key) { 
if (err) 
throw err; 
console.log(key.toString('hex')); // 'c5e478d...1469e50' 
}); 


可 用 通过 crypto.getHashes() 获取 支持 的 摘要 函数 列表 。 


crypto.pbkdf2Sync(password, salt, iterations, keylen[, 
digest]) 


同步 PBKDF2 有 函数 。 返 回 derivedkey 或 抛 出 错误 。 


crypto.randomBytes(size[, callback]) 


生成 有 密码 图 谱 一 般 健 壮 的 伪 随 机 数据 ， 用 处 : 


// async 
crypto.randomBytes(256, function(ex, buf) { 
if (ex) throw ex; 
console.log('Have %d bytes of random data: %s', buf.length, bu 
f); 
}); 


EGM s 

var buf = crypto.randomBytes(256); 

console.log('Have %d bytes of random data: %s', buf.length, bu 
f); 
} catch (ex) { 

‘/ handle error 


Tee aa esas Arto Mparann aa a Eaa ; a 
// most likely, entropy sources are drained 


Ww 


注意 : WRAL PACS 
充 的 


盟 塞 。 尽 管 它 从 不 话费 超过 几 毫 秒 。 唯 一 可 以 想到 的 
阻塞 是 情况 是 ， 当 整个 系统 还 局 
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Class: Certificate 


这 个 类 用 来 处 理 已 签名 公 钥 & HER (challenges) 。 最 常用 的 是 它 的 一 系列 处 
理 <keygen> 7% 4) & 
数 。 http://www.openssl.org/docs/apps/spkac.html ° 


通过 crypto.Certificate 返回 。 


Certificate.verifySpkac(spkac) 


返回 ture 或 false ， 依 赖 于 SPKAC 的 有 效 性 。 


Certificate.exportChallenge(spkac) 


导出 编码 好 的 公 钥 从 指定 的 SPKAC 。 


Certificate.exportPublicKey(spkac) 


导出 编码 好 的 挑战 (challenge) 从 指定 的 SPKAC 。 


crypto.publicEncrypt(public_key, buffer) 
使 用 public_key 加 密 buffer 。 目 前 只 支持 RSA。 


public_key 可 是 是 一 个 对 象 或 一 个 字符 串 。 如 果 public_key 是 一 个 字符 串 ， 
它 会 被 视 作 没有 密码 的 密 钥 并 且 将 使 用 RSA PKCS1 OAEP PADDING ° 
为 RSA 公 负 可 以 用 来 从 你 传递 给 这 个 方法 的 密 钥 来 获取 。 


public_key: 


e key: 一 个 包含 PEM 加 密 的 私 钥 字符 串 

e passphrase : 一 个 可 选 的 私 钥 密码 字符 串 

e padding: 一 个 可 选 的 填充 值 ， 以 下 值 之 一 : 
。constants.RSA_NO_PADDING 
o constants.RSA_PKCS1_PADDING 
o constants.RSA_PKCS1_OAEP_PADDING 
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crypto.publicDecrypt(public_key, buffer) 


详情 参阅 上 文 。 与 crypto.publicEncrypt 有 相同 API。 黑 认 填充 值 
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7 RSA_PKCS1_PADDING ° 


crypto.privateDecrypt(private_key, buffer) 
使 用 private_key 解密 buffer 。 


private_key 可 以 是 一 个 对 象 或 一 个 字符 串 。 如 果 private_key 是 一 个 字符 
串 ， 它 会 当做 没有 密码 的 密 钥 ， 并 且 使 用 RSA PKCS1 OAEP PADDING ° 


public_key: 


e key: 一 个 包含 PEM 加 密 的 私 钥 字符 串 
e passphrase : 一 个 可 选 的 私 钥 密码 字符 囊 
e padding : 一 个 可 选 的 填充 值 ， 以 下 值 之 一 : 
o constants.RSA_NO_PADDING 
o constants.RSA_PKCS1_PADDING 
o constants.RSA PKCS1 OAEP PADDING 


注意 : 所 有 的 填充 值 都 被 常量 模块 所 定义 。 


crypto.privateEncrypt(private_key, buffer) 


详情 参阅 上 文 。 与 crypto.privateDecrypt #78 FAPI ° RU ta 


g 
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crypto. DEFAULT_ENCODING 


RU FG eA TEL FH BR buffer 的 函数 。 默 认 值 是 'buffer' ， 所 以 默认 
是 使 用 Buffer 对 象 的 。 这 被 用 来 与 昌 的 以 'binary' 为 默认 编码 的 程序 更 好 地 


兼容 。 


注意 新 的 程序 仍 可 能 期 望 使 用 buffer ， 所 以 只 将 它 作 为 一 个 临时 措施 。 


近期 的 API 改 变 


Crypto 模块 在 还 没有 统一 的 流 API 概 念 ， 以 及 没有 Buffer 对 象 来 处 理 二 进 制 数 
据 前 就 加 入 了 Node.js 。 

因为 这 样 ， 它 的 流 类 没有 其 他 node.js 类 的 典型 类 ， 而 且 很 多 方法 默认 接受 和 返 
回 二 进 制 字符 串 而 不 是 Buffer 。 这 些 函 数 将 被 改 成 默认 接受 和 返回 Buffer ° 
这 对 于 一 些 但 不 是 所 有 的 使 用 场景 来 说 是 巨大 的 改变 。 

例如 ， 如 果 你 现在 对 Sign 类 使 用 默认 参数 ， 并 且 传 递 verify 类 的 结果 ， 不 检 
查 数据 ， 那 么 在 以 前 它 将 会 继续 工作 。 在 你 曾经 得 到 二 进 制 字符 串 的 地 方 ， 你 将 会 
得 到 一 个 Buffer 。 


但 是 ， 如 果 你 正在 使 用 那些 使 用 字符 串 可 以 ， 但 使 用 Buffer 不 能 工作 的 数据 (如 
连接 它们 ， 存 储 进 数据 库 等 ) 。 或 者 对 crypto 函数 不 传递 编码 参数 来 传递 二 进 制 
字符 串 。 那 么 以 后 ， 你 需要 提供 你 想 要 指定 的 编码 。 如 果 要 将 黑 认 的 使 用 风格 ， 转 
换 为 日 风格 的 话 ， 将 crypto.DEFAULT_ENCODING 域 设 置 为 'binary' 。 注 意 新 
的 程序 仍 可 能 期 望 接受 buffer ， 所 以 这 仅 作 为 一 个 临时 措施 。 


Debugger 


C2 - FE 


V8 自 带 了 一 个 强大 的 调试 器 ， 可 以 从 外 部 通过 TCP 协 议 访问 。 node.js 为 这 个 调 
试 器 内 建 了 一 个 客户 端 ? 要 使 用 它 的 话 ， 使 用 debug 参数 启动 node.js ; 会 出 
现 提示 符 : 


% iojs debug myscript.js 
< debugger listening on port 5858 


connecting... ok 
break in /home/indutny/Code/git/indutny/myscript.js:1 
al x = SF 


2 setTimeout(function () { 
3 debugger; 
debug> 


node.js 的 调试 器 客户 端 并 未 支持 所 有 的 命令 ， 但 是 简单 的 步 进 和 调试 都 是 可 以 
的 。 通 过 在 源 代码 就 放置 debugger; 语句 ， 你 可 以 启用 一 个 断 点 。 


例如 ， 假 设 又 一 个 这 样 的 myscript.js 
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XS; 
setTimeout(function () { 
debugger; 
console.log("world"); 
}, 1000); 


console.log("hello"); 


那么 一 旦 你 打开 调试 器 ， 它 会 在 第 四 行 中 断 。 


% iojs debug myscript.js 
< debugger listening on port 5858 
connecting... ok 
break in /home/indutny/Code/git/indutny/myscript.js:1 
ab Ok = SF 
2 setTimeout(function () { 
3 debugger; 
debug> cont 
< hello 
break in /home/indutny/Code/git/indutny/myscript.js:3 
TX S o 
2 setTimeout(function () { 
3 debugger; 
4 console.log("world"); 
5 }, 1000); 
debug> next 
break in /home/indutny/Code/git/indutny/myscript.js:4 
2 setTimeout(function () { 
3 debugger; 
4 console.log("world"); 
5 }, 1000); 
6 console.log("hello"); 
debug> repl 
Press Ctrl + C to leave debug repl 
aX 
5 
> 2+2 
4 
debug> next 
< world 
break in /home/indutny/Code/git/indutny/myscript.js:5 
3 debugger; 
4 console.log("world"); 
5 }, 1000); 
6 console.log("hello"); 
7 
debug> quit 
% 


repl 命令 允许 你 远程 地 执行 代码 。 next 命令 步 进 到 下 一 行 。 还 有 一 些 其 他 的 
可 用 命令 ， 输 入 help 查看 它们 。 
Watchers 


在 调试 代码 时 ， 你 可 监视 表达 式 和 变量 的 值 。 在 每 个 断 点 ， 监 视 器 列表 上 的 每 个 表 
达 式 会 被 在 当前 上 下 文 执行 ， 并 且 断 点 的 源 代码 前 展示 。 


an areca > 输入 watch("my_expression") ° watchers 打印 可 


用 的 监视 器 。 为 了 移 除 一 个 监视 器 ， 输 入 unwatch("my_expression") ° 
命令 参考 
Stepping 

e cont, c - 继续 执行 


e next, n- eee 

e step, s- 介入 (Step in) 

e out,o- 离开 (Step out) 

o pause - 暂停 代码 执行 ( 类似 开 发 者 工具 中 的 暂停 按钮 ) 


Breakpoints 


e setBreakpoint(), sb() - 在 当前 行 设置 一 个 断 点 

e setBreakpoint(line), sb(line) - 在 指定 行 设置 一 个 断 点 

e setBreakpoint(‘fn()'), sb(...) - 在 函数 体 的 第 一 个 语句 上 设置 断 点 

e setBreakpoint('script.js', 1), sb(...) -在 script.js 的 第 一 行 设置 断 点 
e clearBreakpoint('script.js', 1), cb(...)- 清除 script.js 第 一 行 的 断 点 


同样 也 可 以 在 一 个 还 未 载 入 的 文件 (模块) 中 设置 断 点 : 


% ./10js debug test/fixtures/break-in-module/main.js 
< debugger listening on port 5858 
connecting to port 5858... ok 
break in test/fixtures/break-in-module/main.js:1 
1 var mod = require('./mod.js'); 
2 mod.hello(); 
3 mod.hello(); 
debug> setBreakpoint('mod.js', 23) 
Warning: script 'mod.js' was not loaded yet. 
1 var mod = require('./mod.js'); 
2 mod.hello(); 
3 mod.hello(); 
debug> c 
break in test/fixtures/break-in-module/mod.js:23 
21 
22 exports.hello = function() { 
23 return ‘hello from module'; 
24 }; 
25 
debug> 


Info 


e backtrace, bt - 打印 当前 执行 框架 的 回 漳 

e list(5) - 列 出 脚本 源 代码 的 5 行 上 下 文 (前 5 行 和 后 5 行 ) 

e watch(expr) - 为 监视 列表 添加 表达 式 

e unwatch(expr) - aa 

e watchers - 列 o 监视 器 和 它们 的 值 (会 在 每 一 个 断 点 自动 列 出 ) 
de et ee 


Execution control 


e run- 运行 脚本 (在 调试 器 开始 时 自动 运行 ) 
e restart - ao 启 脚本 
e kill - 结束 脚本 


Various 


e scripts - 列 出 所 有 载 入 的 脚本 


e version - 展示 V8 版 本 


高 级 使 用 
V8 调试 器 可 以 通过 使 用 --debug 命令 行 参数 打开 node.js 或 向 一 个 已 存在 
的 node.js 进程 发 送 SIGUSR1 信号 来 启用 。 
一 旦 一 个 进程 被 设置 为 了 调试 模式 ， 它 就 可 以 被 连接 到 node.js 调试 器 。 可 以 通 
过 pid 或 URI 来 连接 ， 语 法 为 : 

e iojs debug -p - 通过 pid 连 接 进程 

e iojs debug - 通过 URI (如 localhost:5858 ) 连接 进程 


DNS 


PER: 2 - Fh 


通过 require('dns') 来 获取 这 个 模块 。 
这 个 模块 包含 以 下 两 类 函数 : 


1) 使 用 底层 操作 系统 工具 来 进行 域名 解析 的 函数 ， 并 且 不 需要 进行 任何 网 络 活动 。 
这 类 函数 只 有 一 个 : dns.lookup ° #25 在 其 他 操作 系统 的 其 他 应 用 执行 域名 
解析 有 相同 行为 时 ， 请 使 用 dns.lookup ° 


下 面 是 一 个 解析 www.google.com 的 例子 
var dns = require('dns'); 


dns. lookup( 'www.google.com' 


, function onLookup(err, addresses, f 
amily) { 


console.log('addresses:', addresses); 
+); 


2) 连接 实际 的 DNS 服务 器 来 进行 域名 解析 的 函数 ， 并 且 经 常 使 用 网 络 来 执行 DNS 查 
找 。 除 了 dns.lookup 外 DNS 模块 的 所 有 函数 都 属于 这 类 。 这 类 函数 不 

5 dns.lookup 使 用 相同 的 配置 文件 。 例 如 ， 它 们 不 使 用 /etc/hosts 配置 文 
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层 操作 系统 工具 来 进行 域名 解析 ， 总 是 想 要 执 
行 DNS 查 询 的 开发 者 。 


下 面 例子 是 ， 解 析 'www.google.com' ， 然 后 反 向 解析 返回 的 IP 地址 。 


var dns = require('dns'); 


dns.resolve4('www.google.com', function (err, addresses) { 
if (err) throw err; 


console.log('addresses: ' + JSON.stringify(addresses) ); 


addresses.forEach(function (a) { 
dns.reverse(a, function (err, hostnames) { 
if (err) { 
throw err; 


console.log('reverse for ' +a + ': ' + JSON.stringify(hos 
tnames)); 
+); 
+); 
+); 


两 者 之 间 的 选择 会 产生 微妙 的 结果 ， 更 多 信息 请 查询 下 文 实现 注意 事项 章节 。 


dns.lookup(hostnamef[, options], callback) 


解析 hostname (如 'google.com' ) 为 第 一 个 找到 的 A (IPv4) 或 
AAAA (IPv6) 记录 。 options 可 以 是 对 象 或 者 数组 。 如 果 options 没有 提供 ， 
那么 IPv4 和 |Pv6 都 是 有 效 的 。 如 果 options 是 一 个 数组 ， 那 么 它 必 须 


aq 


是 4 或 6。 
另外 ， options 可 以 是 一 个 含有 以 下 属性 的 对 象 : 


e family: {Number} - 地 址 族 。 如 果 提 供 ， 必 须 为 整数 4 或 6 。 如 果 没 有 提 
共 ， 那 么 IPv4 和 IPv6 都 是 有 效 的 。 

e hints: {Number} - 如 果 提 供 ， 它 必须 是 一 个 或 多 个 支持 的 getaddrinfo 标 
识 。 如 果 没 有 提供 ， 那 么 没有 标识 被 传递 给 getaddrinfo 。 多 个 标识 可 以 通 
过 在 逻辑 上 ORing 它们 的 值 ， 来 传递 给 hints 。 支 持 的 getaddrinfo 标识 
请 参阅 下 文 。 

e all: {Boolean} - 如 果 true ， 那 么 回调 函数 以 数组 的 形式 返回 所 有 解析 的 地 
址 ， 否 则 只 返回 一 个 地 址 。 默 认为 false 。 


所 有 的 属性 都 是 可 选 的 ， 以 下 是 一 个 options 例子 : 


{ 
family: 4, 
hints: dns.ADDRCONFIG | dns.V4MAPPED, 
all: false 


回调 函数 有 参数 (err, address, family) 。 address 是 |Pv4 或 IPv6 地 址 字符 
串 。 family Æ adress 的 协议 族 ， 即 4 或 6。 


如 果 options 的 所 有 参数 都 被 设置 ， 那 么 参数 转变 为 (err, 
addresses) > addresses 是 一 个 地 址 和 协议 族 数 组 。 


若 发 生 错 误 ， err 是 错误 对 象 ， err.code 是 错误 码 。 不 仅 在 hostname 不 存在 
时 ， 在 如 没有 可 用 的 文件 描述 符 等 情况 下 查找 失败 ， err,.code 也 会 被 设置 
为 'ENOENT' ° 


dns. lookup 不 需要 与 DNS 协议 有 任何 关系 。 它 仅仅 是 一 个 连接 名 字 和 地 址 的 操 
作 系 统 功能 。 


在 任何 的 node.js 程序 中 ， 它 的 实现 对 表现 有 一 些微 妙 但 是 重要 的 影响 。 在 使 用 


ah 


前 ， 请 花 一 些 时 间 查 阅 实现 注意 事项 章节 。 


dns.lookupService(address, port, callback) 
解析 给 定 的 address 和 port 为 一 个 主机 名 和 使 用 getnameinfo 的 服务 。 


回调 函数 有 参数 (err, hostname, service) 。 hostname 和 service 参数 是 字符 
囊 (如 分 别 为 'localhost' 和 'http' ) ° 


若 发 生 错 误 err 是 错误 对 象 ， err.code 是 错误 码 。 


dns.resolve(hostname[, rrtype], callback) 
使 用 指定 的 rrtype 类 型 ， 解 析 主 机 名 (如 'google.com' ) 为 一 个 记录 数组 。 
有 效 的 rrtype A: 


。'A'(IPV4 地 址 ， 默 认 ) 
。'AAAA' (IPV6 地 址 ) 


o 'MX' (邮件 交换 记录 ) 
。'TXT' (文本 记录 ) 
。'SRV' (SRV 记 录 ) 

。'PTR' (用 于 IP 反 向 查找 ) 
。'NS' (域名 服务 器 记录 ) 
。'CNAME' (别名 记录 ) 
。'SOA' (权限 开始 记录 ) 


回调 函数 有 参数 (err, addresses) 。 address 中 每 个 元 素 的 类 型 由 记录 类 型 所 指 
定 ， 并 且 在 下 文 相应 的 查找 方法 中 有 描述 。 


若 发 生 错 误 ，err 是 错误 对 象 ， err.code 是 下 文 错误 代码 列表 中 的 一 个 。 


dns.resolve4(hostname, callback) 

与 dns.resolve() 相同 ， 但 只 使 用 IPv4 查 询 〈 一 个 记录 ) 。 地 址 是 一 个 IPv4 地 址 
数组 (如 ['74.125.79.104', '74.125.79.105', '74.125.79.106'] ) 。 
dns.resolve6(hostname, callback) 


与 dns.resolve4() 相同 ， 除 了 使 用 IPv6 查 询 (一 个 AAAA 查 询 ) 。 


dns.resolveMx(hostname, callback) 

与 dns,resolve() 相同 ， 但 是 只 用 于 邮件 交换 查询 (MX 记录 ) ° 

地 址 是 一 个 MX 记录 数组 ， 每 一 个 元 素 都 有 一 个 priority 和 一 个 exchange 属性 
(如 [{'priority': 10, 'exchange': 'mx.example.com'},...] ) ° 
dns.resolveTxt(hostname, callback) 


与 dns.resolve() 相同 ， 但 是 只 用 于 文本 查询 (TXT 记录 ) 。 地 址 是 一 

个 hostname 可 用 的 2-d 数 组 (如 [ ['v=spfi ip4:0.0.0.0 ', '~all' ] 

] ) 。 每 个 字数 组 包含 一 个 记录 的 TXT 数据 块 。 根 据 使 用 场景 的 不 同 ， 它 们 可 能 被 
连接 在 一 起 也 可 能 被 分 开 。 


dns.resolveSrv(hostname, callback) 


与 dns.resolve() 相同 ， 但 是 只 用 于 服务 查询 (SRV 记 录 ) 。 地 址 是 一 
个 hostname 可 用 的 SRV 记 录 数 组 。SRV 记 录 的 属性 

有 priority °> weight ， port ， 和 name (如 [{'priority': 10, 
'weight': 5, ‘port’: 21223, 'name': 'service.example.com'}, 


=) ° 
dns.resolveSoa(hostname, callback) 


与 dns.resolve() 相同 ， 但 是 只 用 于 权限 记录 查询 (SOAIZR) 。 


地 址 是 一 个 有 以 下 结构 的 对 象 : 


nsname: 'ns.example.com', 
hostmaster: 'root.example.com', 
serial: 2013101809, 

refresh: 10000, 

retry: 2400, 

expire: 604800, 

minttl: 3600 


dns.resolveNs(hostname, callback) 

与 dns.resolve() 相同 ， 但 是 只 用 于 域名 服务 器 查询 (NS 记录 ) 。 地 址 是 一 
个 hostname 可 用 的 域名 服务 器 记录 数组 (如 ['ns1.example.com', 
'ns2.example.com'] ) ° 

dns.resolveCname(hostname, callback) 

与 dns.resolve() 相同 ， 但 是 只 用 于 别名 记录 (别名 记录 ) 。 地 址 是 一 

个 hostname 可 用 的 别名 数组 (如 ['bar.example.com'] ) ° 
dns.reverse(ip, callback) 

为 得 到 一 个 主机 名 数组 ， 反 向 查询 一 个 I|P 。 


回调 函数 有 参数 (err, hostnames) 。 


若 发 生 错 误 ，err 是 错误 对 象 ， err.code 是 下 文 错误 代码 列表 中 的 一 个 。 


dns.getServers() 


返回 一 个 正在 被 用 于 解析 的 IP 地 址 字符 串 数 组 。 


dns.setServers(servers) 
给 定 一 个 IP 地 址 字符 串 数组 ， 将 它们 设置 给 用 来 解析 的 服务 器 。 
如 果 你 为 地 址 指定 了 一 个 端口 ， 端 口 会 被 忽略 ， 因 为 底层 库 不 支持 。 


如 果 你 传递 了 非法 输入 ， 会 抛 出 错误 。 


Error codes 
每 一 次 DNS 查询 都 可 能 返回 以 下 错误 码 之 一 : 


e dns.NODATA: DNS 服务 器 返回 一 个 没有 数据 的 应 答 o 
e dns.FORMERR: DNS 服务 器 声明 查询 是 格式 错误 的 。 
e dns.SERVFAIL: DNS 服务 器 返回 一 个 普通 错误 。 

e dns.NOTFOUND: 域名 没有 找到 。 

e dns.NOTIMP: DNS 服 务 器 没有 实现 请 求 的 操作 。 

e dns.REFUSED: DNS 服 务 器 拒绝 查询 。 

e dns.BADQUERY: 格式 错误 的 DNS 查询 。 

e dns.BADNAME: 格式 错误 的 主机 名 。 

e dns.BADFAMILY: 不 支持 的 协议 族 。 

e dns.BADRESP: 格式 错误 的 DNS 响应 。 

e dns.CONNREFUSED: 不 能 连接 到 DNS 服务 器 。 

e dns.TIMEOUT': 连接 DNS 服务 器 超时 。 

e dns.EOF: 文件 末端 。 

e dns.FILE: 读 取 文 件 错误 。 

e dns.NOMEM: 内 存 溢出 。 

e dns.DESTRUCTION: 通道 被 销毁 。 

e dns.BADSTR: 格式 错误 的 字符 串 。 

e dns.BADFLAGS: 指定 了 非法 标志 。 

e dns.NONAME: 给 定 的 主机 名 不 是 数字 。 

e dns.BADHINTS: 给 定 的 提示 标识 非法 。 


e dns.NOTINITIALIZED: c-ares 库 初 始 化 未 被 执行 。 

e dns.LOADIPHLPAPI: 加 载 iphlpapi.dll 错误 。 

e dns. ADDRGETNETWORKPARAMS: 找 不 到 GetNetworkParams 函数 。 
e dns.CANCELLED: DNS 查询 被 取消 。 


支持 的 getaddrinfo 标 识 
以 下 标识 可 以 被 传递 给 dns.lookup 的 hints 


e dns.ADDRCONFIG: 返回 的 地 址 类 型 由 当前 系统 支持 的 地 址 类 型 决定 。 例 如 ， 
如 果 当 前 系统 至 少 有 一 个 IPv4 地 址 被 配置 ， 那 么 将 只 会 返回 IPv4 地 址 。 回 泣 地 
址 不 被 考虑 。 

e dns.V4MAPPED: 如 果 IPv6 协 议 族 被 指定 ， 但 是 没有 发 现 IPv6 地 址 ， 那 么 返回 
IPv6 地 址 的 IPv4 映 射 。 


实现 注意 事项 


尽管 dns.lookup 和 dns.resolve*/dns.reverse 函数 都 用 于 关联 一 个 域名 和 一 
个 地 址 (或 反之 亦 然 ) ， 它 们 的 行为 还 是 有 些许 区 别 。 这 些 差别 虽然 微小 ， 但 是 对 
于 node.js 程序 的 行为 有 重大 影响 。 


dns.lookup 


在 引擎 下 ， dns.lookup 使 用 了 和 其 他 程序 相同 的 操作 系统 功能 。 例 

如 ， dns.lookup 将 总 是 和 ping 命令 一 样 解 析 一 个 给 定 的 域名 。 在 大 多 类 
POSIX 操 作 系统 上 ， dns.lookup 函数 的 表现 可 以 通过 改变 nsswitch.conf(5) 
和 /或 resolv.conf(5) 的 设置 来 调整 ， 但 是 需要 小 心 的 是 ， 改 变 这 些 文 件 将 会 影 
响 这 个 操作 系统 上 正在 运行 的 所 有 其 他 程序 。 


BAR JavaScript 的 角度 ， 这 个 调用 是 异步 的 ， 但 是 它 在 libuv 线 程 池 中 的 实现 
是 同步 调用 getaddrinfo(3) 。 因 为 libuv 线 程 池 有 一 个 固定 的 大 小 ， 意 味 着 如 

果 getaddrinfo(3) 花费 了 太 多 的 时 间 ， 那 么 其 他 libuv 线 程 池 中 的 操作 (如 文件 
系统 操作 ) 会 感觉 到 性 能 下 降 。 为 了 缓解 这 个 情况 ， 一 个 潜在 的 解决 方案 是 通过 设 
置 'UV_THREADPOOL_SIZE' 环境 变量 大 于 4 (当前 默认 值 ) 来 增加 libuv 线 程 池 的 大 
小 。 更 多 libuv 线 程 池 的 信息 ， 请 参阅 官方 的 libuv 文 档 。 


dns.resolve， 以 dns.resolve 和 dns.reverse 开 头 的 函数 


这 些 函 数 的 实现 与 dns.lookup 相当 不 同 。 它 们 不 使 用 getaddrinfo(3) 并 且 它 
们 总 是 通过 网 络 执行 一 次 DNS 查询 。 这 些 网 络 通 信 通 常 是 异步 的 ， 并 且 不 使 用 libuv 
线程 池 。 


作为 结果 ， 其 他 使 用 libuv 线 程 池 的 dns.lookup 方法 的 进程 可 能 会 有 相同 的 负面 
影响 ， 但 这 些 函 数 没有 。 


它们 与 dns.lookup 使 用 了 不 同 的 配置 文件 。 例 如 ， 它 们 不 使 用 /etc/hosts 中 
的 配置 。 


Errors 


node.js 生成 的 错误 分 为 两 类 : JavaScript 错误 和 系统 错误 。 所 有 的 错误 都 继 
AF JavaScript 的 Error 类 ， 或 就 是 它 的 实例 。 并 且 都 至 少 提 供 这 个 类 中 可 用 
的 属性 。 


当 一 个 操作 因为 语法 错误 或 语言 运行 时 级 别 (language-runtime-level) 的 原因 不 被 
允许 时 ， 一 个 JavaScript error 会 被 生成 并 抛 出 一 个 异常 。 如 果 一 个 操作 因为 
系统 级 别 (system-level) 限制 而 不 被 允许 时 ， 一 个 系统 错误 会 被 生成 。 客 户 端 代 
码 接 着 会 根据 API 传 播 它 的 方式 来 被 给 予 捕获 这 个 错误 的 机 会 。 


API 被 调用 的 风格 决定 了 生成 的 错误 如 何 回 送 〈handed back) ， 传 播 给 客户 端 。 这 
反 过 来 告诉 客户 端 如 何 捕获 它们 。 蜡 常 可 以 通过 try / catch 结构 捕获 ; 其 他 的 
捕获 方式 请 参阅 下 文 。 

JavaScript 错 误 


JavaScript 错误 表示 API 被 错误 的 使 用 了 ， 或 者 正在 写 的 程序 有 问题 。 


Class: Error 


一 个 普通 的 错误 对 和 象 。 和 其 他 的 错误 对 象 不 同 ， Error 实例 不 指示 任何 AHAB 
误 发 生 的 原因 。 Error 在 它们 被 实例 化 时 ， 会 记录 下 ?堆栈 追踪 ?信息 ， 并 且 可 以 


会 提供 一 个 错误 描述 。 


注意 : node.js 会 将 系统 错误 以 及 JavaScript 错误 都 封装 为 这 个 类 的 实例 。 


new Error(message) 


实例 化 一 个 新 的 Error 对 象 ， 并 且 用 提供 的 message 设置 它 的 .message & 
性 。 它 的 ,stack 属性 将 会 描述 new Error 被 调用 时 程序 的 这 一 刻 。 堆 栈 追 踪 信 
息 隶 属于 V8 堆 栈 追 踪 API。 堆 栈 追 踪 信 息 只 延伸 到 同步 代码 执行 的 开始 ， 

或 Error.stackTraceLimit 给 出 的 帧 数 (number of frames) ， 这 取决 于 哪个 更 
Ws 


error.message 


ony 


一 个 在 Error() 实例 化 时 被 传递 的 字符 串 。 这 个 信息 会 出 现在 堆栈 追踪 信息 的 第 
一 行 。 改 变 这 个 值 将 不 会 改变 堆栈 追踪 信息 的 第 一 行 。 


= 


error.stack 
这 个 属性 返回 一 个 代表 错误 被 实例 化 时 程序 运行 的 那个 点 的 字符 串 。 


一 个 堆栈 追踪 信息 例子 : 


Error: Things keep happening! 

at /home/gbusey/file.js:525:2 

at Frobnicator.refrobulate (/home/gbusey/business-logic.js:42 
4:21) 

at Actor.<anonymous> (/home/gbusey/actors.jsS:400:8) 

at increaseSynergy (/home/gbusey/actors.js:701:6) 


第 一 行 被 格式 化 为 < 错误 类 名 >: < 错误 信息 > ， 然 后 是 一 系列 的 堆栈 信息 帧 

(以 “at” AK) 。 每 帧 都 描述 了 一 个 最 终 导致 错误 生成 的 一 次 调用 的 地 点 。V 
会 试图 去 给 出 每 个 函数 的 名 字 (通过 ， 函 数 名 或 对 象 方法 名 ) ， 但 是 也 有 可 
能 nee 的 名 字 。 如 果 V8 不 能 为 函数 定义 一 个 名 字 ， 那 么 那 一 由 
展示 出 位 置信 息 。 否 则 ， 被 定义 的 函数 名 会 显示 在 位 置信 息 之 前 。 


MASH JavaScript 函数 生成 。 例 如 ， 如 果 在 一 个 JavaScript SRE AH 
执行 了 一 个 叫 cheetahify 的 C++ addon 函数 ， 那 么 堆栈 追踪 信息 中 的 帧 里 将 不 
会 有 cheetahify 调用 : 


Errors 


var cheetahify = require('./native-binding.node'); 


function makeFaster() { 
// cheetahify *synchronously* calls speedy. 
cheetahify(function speedy() { 
throw new Error('oh no!'); 


+); 


makeFaster(); // will throw: 
// /home/gbusey/file.js:6 


// throw new Error('oh no!'); 

// ^ 

MARENKO of no! 

HY at speedy (/home/gbusey/file.js:6:11) 

Mi at makeFaster (/home/gbusey/file.js:5:3) 

Hae at Object.<anonymous> (/home/gbusey/file.js:10:1) 
YH at Module._compile (module.js:456:26) 

HY at Object.Module._extensions..js (module.js:474:10) 
// at Module.load (module.js:356:32) 

I at Function.Module._load (module.js:312:12) 

vive at Function.Module.runMain (module.js:497:10) 

VN at startup (node.js:119:16) 

// at node.js:906:3 


e native ， 如 果 帧 代表 了 向 V8 内 部 的 一 次 调用 (如 在 [].forEach 中 ) ° 

e plain-filename.js:line:colum ， 如 果 帧 代表 了 向 node.js 内 部 的 一 次 
调用 。 

e /absolute/path/to/file.js:line:column ， 如 果 帧 代表 了 向 用 户 程序 或 
其 依赖 的 一 次 调用 。 


关键 的 一 点 是 ， 代 表 了 堆栈 信息 的 字符 串 只 在 需要 被 使 用 时 生成 ， 它 是 惰性 生成 
的 。 


堆栈 信息 的 帧 数 由 Error.stackTraceLimit 或 当前 事件 循环 的 tick 里 可 用 的 
mae 中 小 的 一 方 决 定 。 


系统 级 别 错误 被 作为 增强 的 Error 实例 生成 ， 参 阅 下 文 。 


Error.captureStackTrace(targetObject[, constructorOpt]) 
A targetObject 创建 一 个 .stack 属性 ， 它 代表 


了 Error.captureStackTrace 被 调用 时 ， 在 程序 中 的 位 置 。 


var myObject = {}; 
Error.captureStackTrace(myObject); 


myObject.stack // similar to “new Error().stack- 


追踪 信息 的 第 一 行 ， 将 是 targetObject.toString() 的 结果 ， 而 不 是 一 个 带 
有 ErrorType: 前 级 的 信息 。 


可 选 的 constructorOpt 接收 一 个 函数 。 如 果 指 定 ， 所 有 constructorOpt 以 上 
的 帧 ， 包 括 constructorOpt ， 将 会 被 生成 的 堆栈 追踪 信息 忽略 。 


这 对 于 向 最 终 用 户 隐 藏 实现 细节 十 分 有 用 。 一 个 普遍 的 使 用 这 个 参数 的 例子 


function MYError() 4 
Error.captureStackTrace(this, MyError); 





// without passing MyError to captureStackTrace, the MyError 
// frame would should up in the .stack property. by passing 


// the constructor, we omit that frame and all frames above it. 


new MyError().stack 


Error.stackTraceLimit 


一 个 决定 了 堆栈 追踪 信息 的 堆栈 帧 数 的 属性 (不 论 是 由 new Error().stack 或 
由 Error.captureStackTrace(obj) 生成 ) 。 


初始 值 是 10 。 可 以 被 设置 为 任何 有 效 的 JavaScript 数字 ， 当 值 被 改变 后 ， 就 
会 影响 所 有 的 堆栈 追踪 信息 的 获取 。 如 果 设 置 为 一 个 非 数 字 值 ， 堆 栈 追 踪 将 不 会 获 
取 任 何 一 帧 ， 并 且 会 在 要 使 用 时 报告 undefined 。 


Class: RangeError 


一 个 Error 子 类 ， 表 明了 为 一 个 函数 提供 的 参数 没有 在 可 接受 的 值 的 范围 之 内 ; 
不 论 是 在 一 个 数字 范围 之 外 ， 或 是 在 一 个 参数 指定 的 参数 集合 范围 之 外 。 例 子 : 


require('net').connect(-1); // throws RangeError, port should b 
@ > 0 ca <= 65536 


node.js 会 立刻 生成 并 抛 出 一 个 RangeError 实例 -- 它们 是 参数 验证 的 一 种 形 
Re 


Class: TypeError 


一 个 Error 子 类 ， 表 明了 提供 的 参数 不 是 被 允许 的 类 型 。 例 如 ， 为 一 个 期 望 收 到 
字符 串 参 数 的 函数 ， 传 入 一 个 函数 作为 参数 ， 将 导致 一 个 类 型 错误 。 


require('url').parse(function() { }); // throws TypeError, since 
it expected a string 


node.js 会 立刻 生成 并 抛 出 一 个 TypeError 实例 -- 它们 是 参数 验证 的 一 种 形 
ee 


Class: ReferenceError 


一 个 Error 子 类 ， 表 明了 试图 去 获取 一 个 未 定义 的 对 象 的 属性 。 大 多 数 情 况 下 它 
表明 了 一 个 输入 错误 ， 或 者 一 个 不 完整 的 程序 。 客 户 端 代码 可 能 会 生成 和 传播 这 些 
错误 ， 但 实际 上 只 有 V8 会 。 


doesNotExist; // throws ReferenceError, doesNotExist is not a va 
riable in this program. 


日 


ReferenceError 实例 将 有 一 个 .arguments 属性 ， 它 是 一 个 包含 了 一 个 元 素 的 
数组 。 这 个 元 素 表 示 没 有 被 定义 的 那个 变量 。 


EIM 4i 
doesNotExist; 


} catch(err) { 
err.arguments[0] === 'doesNotExist'; 


o 序 是 动态 生成 并 执行 的 ， 否 则 ， ReferenceErrors 应 该 永远 被 认为 是 
程序 或 其 依赖 模块 的 Dug 。 


Class: SyntaxError 


一 个 Error Ks ， 表 明了 程序 代码 不 是 合法 的 JavaScript 。 这 些 错误 可 能 只 会 
作为 代码 运行 的 结果 生成 。 代 码 运行 可 能 

是 eval ， Function ， require 或 vm 的 结果 。 错误 经 常 表明 了 一 个 不 
完整 的 程序 。 


try { 
require("vm").runInThisContext("binary ! isNotOk"); 


} catch(err) { 
// err will be a SyntaxError 


SyntaxError 对 于 创建 它们 的 上 下 文 来 说 是 不 可 恢复 的 - 它们 仅 可 能 被 其 他 上 下 
文 捕获 。 
异常 VS. 错误 


一 个 JavaScript“ 有 异常? 是 一 个 无 效 操作 或 throw 声明 所 抛 出 的 结果 的 值 。 但 是 
这 些 值 不 被 要 求 必 须 继 承 于 Error 。 所 有 的 由 node.js 或 JavaScript 运行 时 
抛 出 的 异常 都 必须 是 Error 实例 。 


一 些 弄 常 在 JavaScript 层 是 无 法 恢复 的 。 这 些 异常 通常 使 一 个 进程 挂 掉 。 它 们 
通常 无 法 通过 assert() 检查 ， 或 C++ 层 中 的 abort() A o 


系统 错误 


系统 错误 在 程序 运行 时 环境 的 响应 中 生成 。 理 想 情 况 下 ， 它 们 代表 了 程序 能 够 处 理 
的 操作 和 错误。 它们 在 系统 调用 级 别 生 成 : 一 个 详尽 的 错误 码 列 表 和 它们 意义 可 以 通 
过 运行 man 2 intro 或 man 3 errno 在 大 多 数 Unices 中 获得 ; 或 在 线 获得 。 


在 node.js 中 ， 系 统 错误 表现 为 一 个 增强 的 Error 对 象 -- 不 是 完全 的 子 类 ， 而 
是 一 个 有 额外 成 员 的 error 实例 。 


Class: System Error 


error.syscall 


一 个 代表 了 失败 的 系统 调用 的 字符 串 。 
error.errno 


error.code 

一 个 代表 了 错误 码 的 字符 串 ， 通 常 是 大 写字 母 E ， 可 在 man 2 intro 命令 的 结 
果 中 查阅 。 

常见 系统 错误 


这 个 列表 不 详尽 ， 但 是 列举 了 许多 在 写 node.js 的 过 程 中 普遍 发 生 的 系统 错误 。 
详尽 的 列表 可 以 在 这 里 查阅 : http://man7.org/linux/man- 
pages/man3/errno.3.html 


EPERM: 操作 不 被 允许 

试图 去 执行 一 个 需要 特权 的 操作 。 

ENOENT: 指定 的 文件 或 目录 不 存在 

通常 由 文件 操作 产生 ; 指定 的 路 径 不 存在 -- 通过 指定 的 路 径 不 能 找到 实例 (文件 或 
目录 ) 。 

EACCES: 没有 权限 


试图 以 禁止 的 方式 去 访问 一 个 需要 权限 的 文件 。 


EEXIST: 文件 已 存在 


执行 一 个 要 求 目标 不 存在 的 操作 时 ， 一 个 已 存在 文件 已 经 是 目标 。 


ENOTDIR: 非 目录 


给 定 的 路 径 存在 ， 但 不 是 期 望 的 目录 。 通 常 由 fs,readdir 产生 。 


EISDIR: 是 目录 


一 个 操作 期 望 接收 一 个 文件 ， 但 给 定 的 路 径 是 一 个 文件 。 


EMFILE: 系统 中 打开 太 多 文件 


达到 了 系统 中 允许 的 文件 描述 符 的 最 大 数量 ， 那 么 下 一 个 描述 符 请 求 ， 在 已 存在 的 
最 后 一 个 描述 符 关闭 之 前 ， 都 不 能 被 满足 。 


通常 在 并 行 打 开 太 多 文件 时 触发 ， 特 别 是 在 那些 将 进程 可 用 的 文件 描述 符 数 量 限 制 
得 很 低 的 操作 系统 中 (尤其 是 OS X) 。 为 了 改善 这 个 限制 ， 在 同一 个 SHELL 中 运 
行 ulimit -n 2048 命令 ， 再 运行 node.js 进程 。 

EPIPE: 损坏 的 管道 

向 没有 读 取 数 据 进程 的 管道 ，socket 或 FIFO 中 执行 一 个 写 操作 。 通 常 在 网 络 和 http 
层 发 生 ， 表 明 需 要 被 写 入 的 远程 流 已 经 被 关闭 。 

EADDRINUSE: 地 址 已 被 使 用 

试图 给 一 个 服务 器 (net，http 或 https) 绑 定 一 个 本 地 地 址 失败 ， 因 为 另 一 个 本 地 系 
统 中 的 服务 器 已 经 使 用 了 那个 地 址 。 

ECONNRESET: 连接 两 方 重 置 《Connection reset by peer) 
连接 的 双方 被 强行 关闭 。 通 常 是 远程 socket 超时 或 重启 的 结果 。 通 常 

由 http 和 net 模块 产生 。 

ECONNREFUSED: 拒绝 连接 


由 于 目标 机 器 积极 拒绝 ， 没 有 连接 可 以 建立 。 通 常 是 试图 访问 一 个 不 活跃 的 远程 主 
机 的 服务 的 结果 。 


ENOTEMPTY: 目录 不 为 空 


操作 的 实例 要 求 是 一 个 空 目录 ， 但 目录 不 为 空 -- 通常 由 fs.unlink 产生 。 


ETIMEDOUT: 操作 起 时 


因为 被 连接 方 在 一 段 指 定 内 未 响应 ， 连 接 或 发 送 请 求 失败 。 通 常 由 http 或 net 产 生 -- 
经 常 是 一 个 被 连接 socket 没有 合适 地 调用 ,end() 方法 的 标志 。 


错误 的 传播 和 捕获 


所 有 的 node.js API 将 无 效 的 参数 视 作 异常 -- 也 就 是 说 ， 如 果 传 递 了 非法 的 参 
数 ， 他 们 会 立刻 生成 并 抛 出 一 个 error 作为 异常 ， 甚 至 是 异步 API 也 会 。 


同步 API《〈 像 fs.readFileSync ) 将 会 抛 出 一 个 错误 。 抛 出 值 的 行为 是 将 值 包 装 
ASDA o HR TABU try { } catch(err) { } 结果 捕获 。 


异步 API 有 两 种 错误 传播 机 制 ; 一 种 代表 了 单个 操作 (Node 风格 的 回调 函数 ) ， 另 
一 种 代表 了 多 个 操作 (错误 事件 ) 。 


Node 风 格 的 回调 函数 


单个 操作 使 用 Node 风 格 的 回调 函数 -- 一 个 提供 给 API 作 为 参数 的 函数 。Node 风 格 
的 回调 函数 至 少 有 一 个 参数 -- error - CVU null (如 果 没 有 错误 发 生 ) 或 
是 Error 实例 。 例 子 : 


var Ts = require(’fs’); 


fs.readFile('/some/file/that/does-not-exist', function nodeStyle 
Callback(err, data) { 

console.log(err) // Error: ENOENT 

console.log(data) // undefined / null 
}); 


fs.readFile('/some/file/that/does-exist', function(err, data) { 
console.log(err) // null 
console.log(data) // <Buffer: ba dd ca fe> 


}) 


注意 ， try { } catch(err) { 不 能 捕获 异步 API 生 成 的 错误 。 一 个 初学 者 的 
常见 错误 是 尝试 在 Node 风 格 的 回调 函数 中 抛 出 错误 : 


// THIS WILL NOT WORK: 
Var iS = Fequiret is. ); 


try sf 
fs.readFile('/some/file/that/does-not-exist', function(err, da 


ta) { 


// mistaken assumption: throwing here... 
if (err) { 
throw err; 


} 
}); 
} catch(err) { 
// ... will be caught here -- this is incorrect! 
console.log(err); // Error: ENOENT 


这 将 不 会 正常 运行 | 在 Node 风 格 的 回调 函数 执行 时 ， 外 围 的 代码 try { } 
catch(err) { } ) 已 经 退出 了 。 在 大 多 数 情 况 ， 在 Node 风 格 的 回调 函数 内 部 抛 出 
错误 会 使 进程 挂 掉 。 如 果 启 用 了 domain ， 它 们 可 以 捕获 了 被 抛 出 的 错误 ; 相似 
的 ， 如 果 给 process.on('uncaughtException') 添加 了 监听 器 ， 那 么 它 也 将 会 
捕获 错误 。 


错误 事件 


另 一 个 提供 错误 的 机 制 是 error 事件 。 这 常 被 用 在 基于 流 或 基于 event 
emitter 的 API 中 ， 它 们 自身 就 代表 了 一 系列 的 异步 操作 (每 一 个 单一 的 操作 都 可 
WO 

A error 会 被 抛 出 。 此 时 ， 进 程 会 因为 一 个 未 处 理 的 异常 而 挂 掉 ， 除 非 提 供 

适 的 domains ， 或 监听 了 process.on('uncaughtException') ° 


var net = require('net'); 
var connection = net.connect('localhost'); 


// adding an "error" event handler to a stream: 
connection.on('error', function(err) { 
// if the connection is reset by the server, or if it can't 
// connect at all, or on any sort of error encountered by 
// the connection, the error will be sent here. 
console.error(err); 


+); 
connection.pipe(process.stdout); 


“ 当 没 有 没有 监听 错误 时 会 抛 出 错误 "这 个 行为 不 仅 限 与 node.js 提供 的 API -- AP 
创建 的 基于 流 或 event emitters 的 API 也 会 如 此 。 例 子 : 


var events = require('events'); 
var ee = new events.EventEmitter; 


setImmediate(function() { 
// this will crash the process because no "error" event 
// handler has been added. 
ee.emit('error', new Error('This will crash')); 


}); 


与 Node 风 格 的 回调 函数 相同 ， 这 种 方式 产生 的 错误 也 不 能 被 try { } 
catch(err) { } 捕获 -- 它们 发 生 时 ， 外 围 的 代码 已 经 退出 了 。 


Events 


稳定 度 : 2 - 稳定 


node.js 中 的 许多 对 象 触发 事件 : 一 个 net.Server 每 次 被 连接 时 触发 事件 ， 一 
个 fs.readStream 当 文 件 打 开 时 触发 事件 。 所 有 触发 事件 的 对 象 都 

是 events.EventEmitter 的 实例 。 你 可 以 通过 require("events"); 来 取得 这 
个 模块 。 


通常 ， 事 件 名 以 驼峰 字符 串 来 命令 ， 但 是 这 不 是 严格 要 求 的 ， 任 何 字符 串 都 是 可 以 
接受 的 。 


为 了 处 理 触发 的 事件 ， 我 们 将 函数 关联 到 对 象 上 。 这 些 函 数 被 称 为 监听 器 。 在 监听 
器 中 ， this 指向 监听 器 所 关联 的 EventEmitter 实例 。 
Class: events.EventEmitter 


使 用 require('events') 来 获取 这 个 EventEmitter 类 。 


var EventEmitter = require('events'); 


当 一 个 EventEmitter 实例 发 生 了 一 个 错误 ， 一 个 典型 的 做 法 是 触发 一 
个 error 事件 。 error 事件 在 node.js 中 被 视 为 一 个 特殊 的 事件 ， 如 果 没 有 为 
其 添加 监听 器 ， 默 认 的 行为 是 打印 堆栈 追踪 信息 并 推出 程序 。 


所 有 的 EventEmitter 实例 ， 在 被 添加 新 的 监听 器 时 ， 都 会 触发 newListener = 
件 。 当 有 监听 器 被 移 除 时 ， 都 会 触发 removeListener 事件 。 


emitter.addListener(event, listener) 


emitter.on(event, listener) 


为 指定 的 事件 ， 在 其 监听 器 数组 的 末尾 添加 一 个 新 的 监听 器 。 不 会 去 检查 这 个 事件 
是 否 已 经 被 监听 过 。 事 件 的 多 次 触发 会 导致 监听 器 的 多 次 被 调用 。 


server.on('connection', function (stream) { 
console.log('someone connected!'); 


3); 
返回 一 个 emitter ， 所 以 可 以 被 链 式 调用 。 


emitter.once(event, listener) 


为 事件 添加 一 个 一 次 性 监听 器 。 这 个 监听 器 只 会 在 下 次 事件 触发 时 被 调用 ， 之 后 
被 移 除 。 


server.once('connection', function (stream) { 
console.log('Ah, we have our first user!'); 


}); 
返回 一 个 emitter ， 所 以 可 以 被 链 式 调用 。 


emitter.removeListener(event, listener) 


从 监听 器 数组 中 移 除 指 定 事 件 的 一 个 监听 器 。 注 意 : 在 数组 中 ， 此 监听 器 被 移 除 
后 ， 其 之 后 的 监听 器 的 索引 会 被 改变 。 


var callback = function(stream) { 
console.log('someone connected!'); 

J; 

server.on('connection', callback); 

IE ar 


server.removeListener('connection', callback); 


removeListener 一 次 只 会 从 监听 器 数组 中 移 除 一 个 监听 器 。 如 果 特 定 事 件 的 单 
个 的 监听 器 被 添加 了 多 次 ，removeListener 也 必须 调用 同样 多 次 来 移 除 它们 。 


返回 一 个 emitter ° 所 以 可 以 被 链 式 调用 8 


emitter.removeAllListeners([event]) 


定 事 件 的 所 有 监听 器 。 使 用 这 个 方法 来 oa | 建 
加 emitter (如 socket Be fs ) 的 所 有 监听 器 ， 并 不 是 一 个 明智 的 选择 。 


返回 一 个 emitter ， 所 以 可 以 被 链 式 调用 。 


emittersetMaxListeners(n) 


默认 的 ， 当 一 个 特定 事件 被 添加 了 超过 10 个 监听 器 时 ， EventEmitter 会 打印 一 
个 警告 。 i 有 用 的 默认 人 警告。 但 是 显然 ， 并 不 是 所 有 
的 emitter 都 应 当 被 限制 。 这 个 函数 可 以 用 来 增加 这 个 上 限 。 如 果 想 要 无 限制 ， 


请 设置 0 ° 


返回 一 个 emitter ° 所 以 可 以 被 链 式 调用 z 


emitter.getMaxListeners() 


返回 emitter 当前 的 最 大 监听 器 数 的 值 ， 可 能 

是 emitter.setMaxListeners(n) 设置 的 值 ， 或 者 
a 

是 


EventEmitter.defaultMaxListeners ° 


这 个 值 对 于 调节 最 大 监听 器 数 来 避免 不 负责 任 的 警告 或 最 大 监听 器 数 过 大 ， 都 非 
常 有 用 。 


emitter.setMaxListeners(emitter.getMaxListeners() + 1); 
emitter.once('event', function () { 
// do stuff 
emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1 
1 O)); 
}); 


EventEmitter.defaultMaxListeners 


emitter.setMaxListeners(n) 在 实例 级 别 设置 最 大 监听 器 数 。 这 个 类 属性 让 你 
可 以 设置 所 有 EventEmitter 的 默认 最 大 监听 器 数 ， 对 当前 已 创建 的 和 未 来 创建 
的 EventEmitter 都 有 效 。 请 说 懂 使 用 它 。 


注意 ， emitter.setMaxListeners(n) 仍 优先 


于 EventEmitter.defaultMaxListeners ° 


emitter.listeners(event) 
到 回 指定 事件 的 监听 器 数组 。 
server.on('connection', function (stream) { 


console.log('someone connected!'); 


}); 


console.log(util.inspect(server.listeners('connection'))); // 
[Function] ] 


emitter.emit(event[, arg1][, arg2][, ...]) 
使 用 提供 的 参数 ， 执 行 每 一 个 监听 器 。 


如 果 事 件 有 监听 器 ， 那 么 返回 true > GIAE false 。 


Class Method: EventEmitter.listenerCount(emitter, event) 


回 指 定 事 件 的 监听 器 数 。 


Event: 'newListener' 


e event String 事件 名 
e listener Function 事件 监听 器 有 函数 


这 个 事件 在 监听 器 被 添加 前 触发 。 当 这 个 事件 被 触发 时 ， 监 听 器 还 没有 被 添加 到 事 
件 的 监听 器 数组 中 。 在 newListener 事件 的 回调 函数 中 拿 到 事件 名 时 ， 监 听 器 还 
没有 开始 被 添加 到 该 事件 。 


Event: ' removeListener 


e event String 事件 名 
e listener Function 事件 监听 器 函数 


这 个 事件 在 监听 器 被 移 除 后 触发 。 当 这 个 事件 被 触发 时 ， 监 听 器 已 经 从 事件 的 监听 
器 数组 中 被 移 除了 。 


File System 


稳定 度 :2 -稳定 
文件 MO 是 由 标准 POSIX 函 数 的 简单 包装 提供 的 。 通 过 require('fs') 来 使 用 这 个 
模块 。 所 有 的 方法 都 有 蜡 步 和 同步 两 种 形式 。 


异步 形式 的 方法 通常 在 最 后 一 个 参数 上 接受 一 个 回调 函数 。 回 调 函 数 的 参数 则 取决 
于 不 同 的 方法 ， 但 是 第 一 个 参数 总 是 为 异常 所 保留 。 如 果 操作 正常 结束 ， 那 么 第 一 


个 参数 会 是 null X, undefined ° 


妆 同 步 形式 的 方法 产生 异常 时 ， 会 立刻 抛 出 。 你 可 以 使 用 try/catch 捕获 ， 或 让 


它们 冒 泡 。 
下 面 是 一 个 异步 方法 的 例子 
var fs = require('fs'); 
fs.unlink('/tmp/hello', function (err) { 
if (err) throw err; 


console.log('successfully deleted /tmp/hello'); 
+); 


下 面 是 一 个 同步 方法 的 例子 : 
var fs = require('fs'); 


fs.unlinkSync('/tmp/hello'); 
console.log('successfully deleted /tmp/hello'); 


因为 异步 方法 不 能 够 保证 执行 顺序 ， 所 以 下 面 的 例子 很 容易 出 错 : 


fs.rename('/tmp/hello', ‘/tmp/world', function (err) { 
if (err) throw err; 


console.log('renamed complete' ); 

}); 

fs.stat('/tmp/world', function (err, stats) { 
if (err) throw err; 


console.log('stats: ' + JSON.stringify(stats)); 
}); 


© E 


它 需 要 在 fs.rename 后 执行 fs.stat 。 正 确 的 执行 方法 应 如 下 : 


fs.rename('/tmp/hello', '/tmp/world', function (err) { 
if (err) throw err; 


fs. stati /tmp/world’, function (err, stats) { 
if (err) throw err; 


console.log('stats: ' + JSON.stringify(stats)); 
+); 
}); 


在 繁忙 的 进程 中 ， 十 分 推荐 使 用 异步 版 本 的 方法 。 同 步 版 本 的 方法 会 阻塞 进程 ， 直 
到 它们 完成 ， 也 就 是 说 它们 会 暂停 所 有 连接 。 


文件 的 相对 路 径 也 可 以 被 使 用 ， 记 住 路 径 是 相对 于 process.cwd() 的 。 


大 多 数 的 fs 函数 允许 你 省 略 回调 函数 。 如 果 你 省 略 了 ， 将 会 由 一 个 默认 的 回调 函 
数 来 重 抛 出 (rethrows) 错误 。 要 获得 原始 调用 地 点 的 堆栈 追踪 信息 ， 请 设 
置 NODE_DEBUG 环境 变量 


$ cat script.js 

function bad() { 
require('fs').readFile('/'); 

} 

bad(); 


$ env NODE_DEBUG=fs iojs script.js 
fs. 5.66 
throw err; 
A 


Error: EISDIR, read 
at rethrow (fs.js:61:21) 
at maybeCallback (fs.js:79:42) 
at Object.fs.readFile (fs.js:153:18) 
at bad (/path/to/script.js:2:17) 
at Object.<anonymous> (/path/to/script.js:5:1) 
<etc.> 


fs.rename(oldPath, newPath, callback) 

异步 版 本 的 rename(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 
fs.renameSync(oldPath, newPath) 

同步 版 本 的 rename(2) 。 返 回 undefined ° 
fs.ftruncate(fd, len, callback) 

异步 版 本 的 ftruncate(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 
fs.ftruncateSync(fd, len) 


同步 版 本 的 ftruncate(2) 。 返 回 undefined 。 


fs.truncate(path, len, callback) 


异步 版 本 的 truncate(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 第 一 个 参数 也 可 
以 接受 一 个 文件 描述 符 ， 这 样 的 话 ， fs.ftruncate() 会 被 调用 。 


fs.truncateSync(path, len) 


同步 版 本 的 truncate(2) 。 返 回 undefined 。 
fs.chown(path, uid, gid, callback) 

异步 版 本 的 chown(2) 。 回 调 元 数 只 有 一 个 可 能 的 异常 参数 。 
fs.chownSync(path, uid, gid) 

同步 版 本 的 chown(2) ° & undefined ° 
fs.fchown(fd, uid, gid, callback) 

异步 版 本 的 fchown(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 
fs.fchownSync(fd, uid, gid) 

同步 版 本 的 fchown(2) 。 返 回 undefined 。 
fs.lchown(path, uid, gid, callback) 

异步 版 本 的 lchown(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 
fs.lchownSync(path, uid, gid) 

同步 版 本 的 lchown(2) 。 返 回 undefined ° 
fs.chmod(path, mode, callback) 

异步 版 本 的 chmod(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 
fs.chmodSync(path, mode) 

同步 版 本 的 chmod(2) ° AE undefined ° 


fs.fchmod(fd, mode, callback) 


异步 版 本 的 fchmod(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 


fs.fchmodSync(fd, mode) 


同步 版 本 的 fchmod(2) ° 2% undefined ° 


fs.Ichmod(path, mode, callback) 
异步 版 本 的 lchmod(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 


仅 在 Mac OS X 中 可 用 。 


fs.IchmodSync(path, mode) 


同步 版 本 的 Ichmod(2) 。 返 回 undefined ° 


fs.stat(path, callback) 

异步 版 本 的 stat(2) 。 回 调 函 数 有 两 个 参数 (err, stats) > stats 是 一 
个 fs.Stats 对 象 。 更 多 信息 请 参阅 fs.Stats 章节 。 
fs.lstat(path, callback) 


异步 版 本 的 lstat(2) ° WARA ASAA (err, stats) ， stats 是 一 
个 fs.Stats THe lstat() 与 stat() 是 相同 的 ， 除 了 path 是 一 个 符号 链 
接 ， 连 接 自己 本 身 就 是 stat-ed ， 而 不 是 引用 一 个 文件 。 


fs.fstat(fd, callback) 


异步 版 本 的 fstat(2) 。 回 调 函 数 有 两 个 参数 (err, stats) > stats 是 一 
个 fs.Stats 对 象 。 fstat() 与 stat() 是 相同 的 ， 除 了 将 要 被 stat-ed VX 
件 是 通过 文件 描述 符 fd 来 指定 的 。 


fs.statSync(path) 


同步 版 本 的 stat(2) 。 返 回 一 个 fs.Stats 实例 。 


fs.lstatSync(path) 


同步 版 本 的 lstat(2) 。 返 回 一 个 fs.Stats 实例 。 


fs.fstatSync(fd) 


同步 版 本 的 fstat(2) 。 返 回 一 个 fs.Stats 实例 。 


fs.link(srcpath, dstpath, callback) 


异步 版 本 的 link(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 


fs.linkSync(srcpath, dstpath) 


同步 版 本 的 link(2) ° 2 undefined ° 


fs.symlink(destination, path[, type], callback) 


异步 版 本 的 symlink(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 type 参数 可 以 
被 设置 为 'dir' > 'file' 或 'junction' (RUA 'file' ) > FARE 
Windows 平 台 下 可 用 (其 他 平台 下 会 被 忽略 ) 。 注 意 Windows junction 点 要 求 
目标 路 径 必 须 是 绝对 的 。 当 使 用 'junction' 时 ，destination 参数 会 被 自动 转 
换 为 绝对 路 径 。 

fs.symlinkSync(destination, path[, type]) 


同步 版 本 的 symlink(2) ° 2% undefined ° 


fs.readlink(path, callback) 


异步 版 本 的 link(2) 。 回 调 函 数 有 两 个 参数 (err, linkString) ° 


fs.readlinkSync(path) 


异步 版 本 的 readlink(2) ， 返 回 一 个 符号 链接 字符 串 值 。 


fs.realpath(path[, cache], callback) 


异步 版 本 的 realpath(2) 。 回 调 函 数 有 两 个 参数 (err, resolvedPath) 。 可 能 会 
使 用 process.cwd 来 解析 相对 路 径 。 cache 是 一 个 包含 了 路 径 映 射 的 对 象 ， 被 
用 来 强制 进行 指定 的 路 径 解析 或 避免 对 丨 实 路 径 调 用 额外 的 fs.stat 。 


例子 : 


var cache = {'/etc':'/private/etc'}; 

fs.realpath('/etc/passwd', cache, function (err, resolvedPath) { 
if (err) throw err; 
console.log(resolvedPath); 


}); 


fs.realpathSync(path[, cache]) 


同步 版 本 的 realpath(2) ， 返 回 一 个 解析 出 的 路 径 。 


fs.unlink(path, callback) 


异步 版 本 的 unlink(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 


fs.unlinkSync(path) 


同步 版 本 的 unlink(2) ° 3& undefined ° 


fs.rmdir(path, callback) 


异步 版 本 的 rmdir(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 


fs.rmdirSync(path) 


同步 版 本 的 rmdir(2) ° & undefined ° 


fs.mkdir(path[, mode], callback) 

异步 版 本 的 mkdir(2) 。 回 调 函数 只 有 一 个 可 能 的 异常 参数 。 mode Rik 
为 00777 ° 

fs.mkdirSync(path[, mode]) 


同步 版 本 的 mkdir(2) 。 返 回 undefined ° 


fs.readdir(path, callback) 


异步 版 本 的 readdir(3) ° RA RAX ° HAHAA ANAA (err, 
files) > files 是 一 个 目录 中 的 文件 名 数组 (不 包括 !.! 和 '.,.' ) © 


fs.readdirSync(path) 


同步 版 本 的 readdir(3) 。 返 回 一 个 文件 名 数组 (不 包括 ',， Fe '..' ) © 


fs.close(fd, callback) 


异步 版 本 的 close(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 


fs.closeSync(fd) 


同步 版 本 的 close(2) 。 返 回 undefined ° 


fs.open(path, flags[, mode], callback) 
异步 版 本 的 文件 打开 。 参 阅 open(2) 。 flag 可 以 是 : 
e -以 只 读 的 方式 打开 文件 。 如 果 文件 不 存在 则 抛 出 异常 。 
e rH- 以 读 写 的 方式 打开 文件 。 如 果 文 件 不 存在 则 抛 出 异常 。 
eo 'rs'- 同步 地 以 只 读 的 方式 打开 文件 。 绕 过 操作 系统 的 本 地 文件 系统 缓存 。 


该 功能 主要 用 于 打开 NFS 挂 载 的 文件 ， 因 为 它 允 许 你 跳 过 潜在 的 过 时 的 本 地 缓存 。 
它 对 |/O 性 能 有 非常 大 的 影响 ， 所 以 除非 需要 它 ， 否 则 不 应 使 用 这 个 flag ° 
注意 这 个 flag 不 会 将 fs.open() 变 为 一 个 同步 调用 。 因 为 如 果 你 想 要 同步 调 


用 ， 你 应 使 用 fs.openSync() ° 
e 'rs+ - 以 读 写 的 方式 打开 文件 ， 告 诉 操作 系统 同步 地 打开 它 。 注 意 事项 请 参 
阅 'rs' e 


。'W' - 以 只 写 的 方式 打开 文件 。 如 果 文 件 不 存在 ， 将 会 创建 它 。 如 果 已 存在 ， 将 
会 覆盖 它 


Tm 


o 


e 'WX' - RUT 'w' ， 但 是 路 径 不 存在 时 会 失败 。 


o WH - 以 读 写 的 方式 打开 文件 。 如 果 文 件 不 存在 ， 将 会 创建 它 。 如 果 已 存在 ， 
将 会 覆盖 它 。 


o 'wxt'- RUT 'w+' ， 但 是 路 径 不 存在 时 会 失败 。 


e 'a' - 以 附加 的 形式 打开 文件 。 如 果 文 件 不 存在 ， 将 会 创建 它 。 


o 'aX' - RUF 'a' ， 但 是 路 径 不 存在 时 会 失败 。 
e ‘at! - 以 读 取 和 附加 的 形式 打开 文件 。 如 果 文 件 不 存在 ， 将 会 创建 它 。 
e 'ax+' - RUF 'at' ， 但 是 路 径 不 存在 时 会 失败 。 


参数 mode 用 于 设置 文件 模式 (权限 和 sticky bits ) ， 但 是 前 提 是 文件 已 被 创 
建 。 它 默认 为 9666 ， 有 可 读 和 可 写 权 限 。 


回调 函数 有 两 个 参数 (err, fd) ° 


排除 标识 'x' ( open(2) 中 的 0_EXCL 标识 ) 保证 了 目录 是 被 新 创建 的 。 在 
POSIX 系 统 上 ， 即 使 路 径 指 向 了 一 个 不 存在 的 符号 链接 ， 也 会 被 认定 为 文件 存在 。 
排除 标识 不 能 保证 在 网 络 文件 系统 中 有 效 。 


在 Linux 下 ， 无 法 对 以 追加 形式 打开 的 文件 ， 在 指定 位 置 写 入 数据 。 内 核 忽 略 了 位 置 
参数 并 且 总 是 将 数据 追加 到 文件 的 末尾 。 
fs.openSync(path, flags[, mode]) 


同步 版 本 的 fs.open() ， 返 回 代表 文件 描述 符 的 一 个 整数 。 
fs.utimes(path, atime, mtime, callback) 

更 改 path 所 指向 的 文件 的 时 间 改 。 
fs.utimesSync(path, atime, mtime) 

同步 版 本 的 fs.utimes() 。 返 回 undefined ° 
fs.futimes(fd, atime, mtime, callback) 

更 改 文件 描述 符 fd 所 指向 的 文件 的 时 间 改 。 
fs.futimesSync(fd, atime, mtime) 


同步 版 本 的 fs.futimes() 。 返 回 undefined 。 


fs.fsync(fd, callback) 


异步 版 本 的 fsync(2) 。 回 调 函 数 只 有 一 个 可 能 的 异常 参数 。 


fs.fsyncSync(fd) 


同步 版 本 的 fsync(2) ° & undefined ° 


fs.write(fd, buffer, offset, length[, position], callback) 
向 文件 描述 符 fd 指向 的 文件 写 入 buffer 。 
offset 和 length 决定 了 buffer 的 哪 一 部 分 被 写 入 文件 。 


position 指定 了 文件 中 ， 数 据 被 写 入 的 开始 位 置 的 偏 移 量 。 如 果 typeof 
position !== 'number' ， 那 么 数据 将 会 在 当前 位 置 被 写 入 。 参 
bi] pwrite(2) ° 


Bi] HAA =H (err, written, buffer) 。 written 指出 了 buffer 中 有 多 少 
字 节 被 写 入 。 

注意 ， 不 等 待 回调 函数 而 多 次 执行 fs.write 是 不 安全 的 。 这 种 情况 下 推荐 使 

用 fs.createwriteStream ° 


在 Linux 下 ， 无 法 对 以 追加 形式 打开 的 文件 ， 在 指定 位 置 写 入 数据 。 内 核 忽略 了 位 置 
参数 并 且 总 是 将 数据 追加 到 文件 的 末尾 。 


fs.write(fd, data[, position[, encoding]], callback) 


向 文件 描述 符 fd 指向 的 文件 写 入 data 。 如 果 data 不 是 一 个 Buffer 实例 ， 
那么 其 值 将 被 强制 转化 为 一 个 字符 串 。 


position 指定 了 文件 中 ， 数 据 被 写 入 的 开始 位 置 的 偏 移 量 。 如 果 typeof 
position !== 'number' ， 那 么 数据 将 会 在 当前 位 置 被 写 入 。 参 
阅 pwrite(2) ° 


encoding ÆA Z 19 Fit P z o 


回调 函数 有 三 个 参数 (err, written, buffer) 。 written 指出 了 buffer 中 有 多 少 
字 节 被 写 入 。 注 意 ， 写 入 的 字 节 与 字符 串 字 符 是 不 同 的 。 参 
阅 Buffer.byteLength ° 


与 写 入 buffer 不 同 ， 整 个 字符 串 都 必须 被 写 入 。 不 能 指定 子 字 符 串 。 因 为 字 节 的 
偏 移 量 可 能 与 字符 串 的 偏 移 量 不 相同 。 


注意 ， 不 等 待 回调 函数 而 多 次 执行 fs.write 是 不 安全 的 。 这 种 情况 下 推荐 使 


用 fs.createwriteStream 。 


在 Linux 下 ， 无 法 对 以 追加 形式 打开 的 文件 ， 在 指定 位 置 写 入 数据 。 内 核 忽略 了 位 置 
参数 并 且 总 是 将 数据 追加 到 文件 的 末尾 。 


fs.writeSync(fd, buffer, offset, length[, position]) 


fs.writeSync(fd, data[, position[, encoding]]) 


同步 版 本 的 fs.write() 。 返 回 被 写 入 的 字 节 数 。 


fs.read(fd, buffer, offset, length, position, callback) 
从 文件 描述 符 fd 指向 的 文件 读 取 数 据 。 

buffer 是 数据 将 要 被 写 入 的 缓冲 区 。 

offset 是 开始 向 buffer 写 入 数据 的 缓冲 区 偏 移 量 。 

length 是 一 个 指定 了 读 取 字 节 数 的 整数 。 


position 是 一 个 指定 了 从 文件 的 何 处 开始 读 取 数据 的 整数 。 如 
果 position 是 null ， 数 据 将 会 从 当前 位 置 开始 读 取 。 


回调 函数 有 三 个 参数 (err, bytesRead, buffer) 。 


fs.readSync(fd, buffer, offset, length, position) 


同步 版 本 的 fs.read 。 返 回 读 取 字 节 的 个 数 。 


fs.readFile(filename[, options], callback) 


e filename String 

e options Object | String 
o encoding String | Null 默认 为 null 
o flag String RUX 'r' 

e callback Function 


异步 得 读 取 文 件 的 所 有 内 容 。 例 子 : 


fs.readFile('/etc/passwd', function (err, data) { 
if (err) throw err; 
console.log(data); 


}); 


回调 函数 有 两 个 参数 (err data) > data 是 文件 的 内 容 。 
如 果 没 有 指定 编码 ， 那 么 将 会 返回 源 buffer 。 


如 果 options 是 一 个 字符 串 ， 那 么 它 将 指定 编码 ， 例 子 : 


fs.readFile('/etc/passwd', 'utf8', callback); 


fs.readFileSync(filename[, options]) 
同步 版 本 的 fs.readFile 。 返 回 文件 的 内 容 。 


如 果 指 定 了 编码 那么 将 会 返回 字符 串 。 和 否则 返回 buffer 。 


fs.writeFile(filename, data[, options], callback) 


e filename String 

e data String | Buffer 

e options Object | String 
o encoding String | Null 默认 为 'utfs' 
o mode Number 默认 为 00666 
o flag String 默认 为 'w' 

e callback Function 


异步 地 向 文件 写 入 数据 ， 如 果 文 件 已 经 存在 ， 那 么 会 覆盖 它 。 data 可 以 是 一 个 字 
符 串 或 一 个 buffer 。 


如 果 数 据 时 一 个 buffer 那么 编码 会 被 忽略 。 编 码 默认 为 'utf8' ° 


例子 : 


fs.writeFile('message.txt', 'Hello node.js', function (err) { 
if (err) throw err; 
console.log('It\'s saved!'); 


}); 
如 果 options 是 一 个 字符 串 ， 那 么 它 将 指定 编码 ， 例 子 : 


fs.writeFile('message.txt', 'Hello node.js', 'utf8', callback); 


fs.writeFileSync(filename, data[, options]) 


同步 版 本 的 fs.writeFile 。 返 回 undefined 。 


fs.appendFile(filename, data[, options], callback) 


e filename String 

e data String | Buffer 

e options Object | String 
o encoding String | Null 默认 为 'utf8' 
o mode Number 默认 为 00666 
o flag String RUA 'a' 

e callback Function 


异步 地 向 文件 追加 数据 ， 如 果 文 件 不 存在 将 会 创建 它 。 data 可 以 是 一 个 字符 串 或 


一 个 buffer 。 


例子 : 
fs.appendFile('message.txt', 'data to append', function (err) { 
if (err) throw err; 


console.log('The "data to append" was appended to file!'); 


4); 


如 果 options 是 一 个 字符 串 ， 那 么 它 将 指定 编码 ， 例 子 : 


fs.appendFile('message.txt', 'data to append', ‘utf8', callback) 
fs.appendFileSync(filename, data[, options]) 


同步 版 本 的 fs.appendFile ° &X undefined ° 


fs.watchFile(filename[, options], listener) 
US AL SC ENG o BIHAR listener 会 在 文件 每 一 次 被 访问 时 调用 。 


第 二 参数 是 可 选 的 。 如 果 options 被 提供 ， 那 么 它 必 须 是 一 个 含有 两 个 成 

员 persistent 和 interval 的 对 象 。 persistent 表明 了 进程 是 否 在 文件 被 监 
视 时 继续 执行 。 interval 表明 了 文件 被 轮 询 的 间隔 (毫秒 ) 。 默 认 是 { 
persistent: true, interval: 5007 } ° 


listener 有 两 个 参数 ， 当 前 状态 对 象 和 先前 状态 对 象 : 


fs.watchFile('message.text', function (curr, prev) { 


console.log('the current mtime is: ' + curr.mtime); 
console.log('the previous mtime was: ' + prev.mtime); 
}); 


这 两 个 状态 对 象 都 是 fs.Stat 实例 。 


果 你 想 要 在 文件 被 修改 时 被 通知 ， 而 不 仅仅 是 在 被 访问 时 ， 你 需要 比 


curr.mtime 和 prev.mtime ° 

注意 : fs.watch 比 fs.watchFile 和 fs.unwatchFile 更 高 效 。 当 可 能 时 ， 请 
使 用 fs.watch 替代 它们 。 

fs.unwatchFile(filename[, listener]) 


停止 监视 filename 的 变化 。 如 果 指 定 了 listener ， 那 么 仅仅 会 移 除 指定 
的 listener 。 否 则 所 有 的 监听 器 都 会 被 移 除 ， 并 且 停 止 继续 监视 文件 。 


一 个 没有 被 监视 的 文件 调用 fs.unwatchFile() 将 不 会 发 生 任何 事 ， 而 不 是 报 
错 。 


注意 : fs.watch tt fs.watchFile 和 fs.unwatchFile 更 高 效 。 当 可 能 时 ， 请 
使 用 fs.watch 替代 它们 。 


fs.watch(filename[, options]|[, listener]) 


监视 filename 的 变化 ， filename 指向 的 可 以 是 文件 也 可 以 是 目录 。 返 回 一 
个 fs.FSWatcher 对 象 。 


第 二 个 参数 是 可 选 的 。 options 必须 是 一 个 对 象 。 支 持 的 布尔 值 属性 

是 persistent 和 recursive ° persistent 表明 了 进程 是 否 在 文件 被 监视 时 
继续 执行 。 recursive 表明 了 是 否 子 目录 也 需要 被 监视 ， 或 仅仅 监视 当前 目录 。 
这 只 在 支持 的 平台 (参阅 下 方 警告 ) 下 传递 一 个 目录 时 有 效 。 


默认 是 { persistent: true, recursive: false } ° 


listener 回调 函数 有 两 个 参数 (event, 
filename) 。 event 是 'rename' 或 'change' ， filename 是 触发 事件 的 文 
件 名 。 


ie 
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fs.watch API 不 是 在 所 有 平台 下 都 表现 一 致 的 ， 并 且 在 一 些 情况 下 是 不 可 用 
A 


recursive 选项 目前 只 支持 OS X° RA FSEvents 支持 这 种 类 型 的 文件 监控 ， 
所 有 其 他 平台 并 不 会 很 快 都 被 支持 。 


可 用 性 
这 个 特性 依赖 于 底层 操作 系统 提供 的 文件 变化 提示 。 


e 在 Linux 系 统 下 ， 它 使 用 inotify ° 

e 在 BSD 系 统 下 ， 它 使 用 kqueue ° 

e 在 OS X 下 ， 对 于 文件 它 使 用 kqueue ， 对 于 目录 它 使 用 FSEvents ° 

e 在 SunOS 系 统 (包括 Solaris 和 smart0S ) 下 ， 它 使 用 事件 端口 (event 
ports) 。 

e 在 Windows 系 统 下 ， 这 个 特性 依赖 于 ReadDirectoryChangesw 。 


如 果 由 于 一 些 原 因 ， 底 层 功 能 不 可 用 ， 那 么 fs.watch 的 功能 也 将 不 可 用 。 例 如 ， 
在 网 络 文件 系统 (NFS，SMB 等 ) 中 监视 文件 或 目录 变化 ， 往 往 结果 不 可 靠 或 完全 
不 可 用 。 


你 仍 可 以 使 用 fs.watchFile ， 它 使 用 了 状态 轮 询 。 但 是 性 能 更 差 且 可 人 靠 性 更 
低 。 


Filename 参数 


回调 函数 中 提供 的 filename 参数 不 是 在 所 有 平台 上 都 支持 的 (目前 只 支持 Linux 
FeWindows) 。 即 使 是 在 支持 的 平台 上 ， filename 也 不 是 总 会 被 提供 。 因 此 ， 不 
要 假设 filename 参数 总 会 在 回调 函数 中 被 提供 ， 需 要 有 一 些 检 测 它 是 否 

为 null 的 逻辑 。 


fs.watch('somedir', function (event, filename) { 


console.log('event is: ' + event); 
if (filename) { 
console.log('filename provided: ' + filename); 
} else { 
console.log('filename not provided'); 
} 
}); 


fs.exists(path, callback) 
fs.exists() 已 被 育 用 。 请 使 用 fs.stat 或 fs.access 替代 。 
检查 文件 系统 来 测试 提供 的 路 径 是 否 存 在 。 然 后 在 回调 函数 的 参数 中 提供 结 


Æ true 或 false 


fs.exists('/etc/passwd', function (exists) { 
util.debug(exists ? "it's there" : "no passwd!"); 


+); 
fs.exists() 是 一 个 不 符合 潮流 的 函数 ， 并 且 仅 因 一 些 历史 原因 所 以 仍然 错 在 。 
在 你 的 代码 中 ， 不 应 有 任何 原因 要 继续 使 用 它 。 


特别 的 ， 在 打开 文件 前 检查 文件 是 否 存在 是 一 种 反 模 式 。 因 为 竞 态 条 件 所 以 让 你 的 
代码 十 分 脆弱 : 其 他 进程 可 能 fs.exists() 和 fs.open() 之 问 删除 文件 。 所 以 
仅仅 就 去 打开 一 个 文件 ， 并 且 当 它 不 存在 时 处 理 错误 。 


fs.existsSync(path) 


同步 版 本 的 fs.exists 。 当 文件 存在 ， 返 回 true > GIAE false 。 


fs.existsSync() 已 被 弃 用 。 请 使 用 fs.statSync 或 fs.accessSync 替代 。 


fs.access(path[, mode], callback) 


对 于 指定 的 路 径 ， 检 测 用 户 的 权限 。 mode 是 一 个 可 选 的 整数 ， 指 定 了 要 被 执行 的 
可 访问 性 检查 。 以 下 是 mode 的 一 些 可 用 的 常量 。 可 以 通过 “或 "运算 符 (|) 连接 两 
个 或 以 上 的 值 。 


e fs.F_OK - -o 程 可 见 。 这 对 于 检查 文件 是 否 存在 很 有 用 ， 但 是 不 
提供 任何 rwx 权限 信息 。 这 是 默认 值 。 

e fs.R_OK -文件 对 于 当前 进程 可 读 。 

e fs.W_OK -文件 对 于 当前 进程 可 写 。 

e fs.X_OK -文件 对 于 当前 进程 可 执行 。 这 在 Windows 上 无 效 (将 会 表现 得 
像 fs.F_OK 一 样 ) 。 


最 后 一 个 参数 callback ， 是 一 个 包含 了 潜在 错误 参数 的 回调 函数 。 如 果 任 何 一 个 
可 访问 检查 失败 了 ， 错 误 参 数 就 会 被 提供 。 以 下 是 一 个 在 当前 进程 中 检 
查 /etc/passwd 可 读 性 和 可 写 性 的 例子 。 


fs.access('/etc/passwd', fs.R_OK | fs.W_OK, function(err) { 
util.debug(err ? 'no access!' : 'can read/write'); 


PIi 


fs.accessSync(path[, mode]) 


同步 版 本 的 fs.access 。 如 果 任 何 一 个 可 访问 性 检查 失败 了 ， 它 会 抛 出 异常 。 否 
则 什么 都 不 做 。 


Class: fs.Stats 


由 fs.stat() > fs.lstat() ， fs.lstat() 和 它们 的 同步 版 本 函数 所 返回 的 
对 象 。 


e stats.isFile() 

e stats.isDirectory() 

e stats.isBlockDevice() 

e stats.isCharacterDevice() 


e stats.isSymbolicLink() ( 仅 在 调用 fs.istat() 时 有 效 ) 


e stats.isFIFO() 
e stats.isSocket() 


对 于 一 个 普通 的 文件 ， 


{ dev: 2114, 
ino: 48064969, 
mode: 33188, 
nlink: 1, 
uid: 85, 
gid: 100, 
rdev: 0, 
size: 527, 
blksize: 4096, 
blocks: 8, 
atime: Mon, 10 
mtime: Mon, 10 
ctime: Mon, 10 


birthtime: Mon, 


util.inspect(stats) 可 能 会 返回 : 


Oct 2011 23524591 GMT, 
Oct 2011 23:24:11 GMT, 
Oct 2011123: 24: TIGMI, 
10 0ct 2011 23:24:11 GMI 7 


请 注意 ， atime ， mtime ， birthtime 和 ctime 都 是 Date 对 象 实例 ， 并 且 


你 可 以 通过 合适 的 方法 来 比较 它们 的 值 。 普 遍 


局 的 使 用 方式 是 ， 调 用 getTime() 来 


ARKI ARSE LRM AC AT va AL RA 行 任 何 比较 。 但 是 还 有 一 些 可 以 展示 模 


糊 信 息 的 方法 。 更 多 的 详细 信息 请 参阅 MDN JavaScript Reference 


Stat 时 间 值 


stat 对 象 中 的 各 个 时 间 有 如 下 语义 : 


e atime "访问 时 间 " - 


由 mknod(2) ， 


e mtime "修改 时 间 " - 


由 mknod(2) ， 


e ctime "改变 时 间 " - 


由 chmod(2) ， 


e birthtime "创建 时 间 " - 文件 的 创建 时 间 。 在 文件 被 创建 时 设置 。 在 


文件 数据 最 后 一 次 被 访问 时 的 时 间 。 
utimes(2) 和 read(2) 系统 调用 改变 。 
文件 数据 最 后 一 次 被 修改 的 时 间 。 
utimes(2) 和 write(2) 系统 调用 改变 。 


页 。 


文件 状态 最 后 一 次 被 改变 (索引 节点 改变 ) 的 时 间 。 


chown(2) ， link(2) > mknod(2) > rename(2) ， un 
link(2) ， utimes(2) ° read(2) 和 write(2) 系统 调用 改变 。 


创建 时 间 不 


可 用 的 的 文件 系统 上 ， 这 个 值 可 能 会 被 ctime 或 是 1970-01- 

91T00:00Z (unix 时 间 惟 0) 填充 。 在 Darwin 或 其 他 FreeBSD 系 统 变 体 上 ， 如 
果 使 用 utimes(2) 系统 调用 设置 atime 为 一 个 比 当前 birthtime 更 早 的 
时 间 ， birthtime 也 会 被 这 样 卉 充 。 


在 node.js v1.0 和 Node v0.12 前 ，Windows 系 统 中 ctime 持 有 
了 birthtime 值 。 但 是 在 v0.12 里 ， ctime 不 再 是 “创建 时 间 ”。 在 Unix 系 统 中 ， 
它 从 来 都 不 是 。 


fs.createReadStream(path[, options]) 
返回 一 个 新 的 可 读 流 对 象 〈 参 阅 Readable Stream ) ° 
options 是 一 个 有 以 下 默认 值 的 对 象 或 字符 串 : 
个 lags. na, 
encoding: null, 
Tos 10 ls 


mode: 00666, 
autoClose: true 


options 可 以 包含 start 和 end 值 来 读 取 指 定 范围 的 文件 数 

据 。 start 和 end 这 两 个 位 置 本 身 ， 也 都 是 被 包括 的 ， 并 且 start 以 9 开 
始 。 编 码 可 以 是 'utf8' > 'ascii' 或 'base64' ° 

如 果 指 定 了 fd ， 可 读 流 将 会 忽略 path 参数 并 且 将 会 使 用 指定 的 文件 描述 符 。 这 
意味 open 事件 不 再 会 触发 。 

如 果 autoClose 为 false ， 和 那么 文件 描述 符 将 不 会 被 关闭 ， 甚 至 是 有 错误 发 生 
时 。 关 闭 它 将 是 你 的 责任 ， 并 且 要 确保 没有 文件 描述 符 汇 漏 。 如 

Æ autoClose 为 true (Ki) ， 那 么 在 发 生 错 误 时 ， 或 到 达 文 件 描述 末端 时 ， 


它 会 被 自动 关闭 。 


从 一 个 100 字 节 的 文件 中 读 取 最 后 10 字 节 数 据 的 例子 : 


fs.createReadStream('sample.txt', {start: 90, end: 99}); 


如 果 options 是 一 个 字符 串 ， 那 么 它 表 示 指 定 的 编码 。 


Class: fs.ReadStream 


ReadStream 是 一 个 可 读 流 。 


Event: ‘open' 
e fd Integer 被 可 读 流 使 用 的 文件 描述 符 


当 可 读 流 文件 被 打开 时 触发 。 


fs.createWriteStream(path[, options]) 
返回 一 个 新 的 可 写 流 对 象 (参阅 writable Stream ) ° 
options 是 一 个 有 以 下 默认 值 的 对 象 或 字符 串 : 
{ flags: ‘w', 
encoding: null, 


wole mwami 
mode: 00666 } 


options 可 以 包含 一 个 start 选项 来 允许 从 指定 位 置 开 始 写 入 数据 。 修 改 一 个 
文件 而 不 是 替换 它 ， 需 要 一 个 r+ 标识 ， 而 不 是 默认 的 Ww 。 编 码 可 以 


是 'utf8' > 'ascii' ， 'binary' 或 'base64' 。 


与 上 文 的 ReadStream 类 似 ， 如 果 指 定 了 fd > TAAAK path 参数 ， 并 且 
使 用 指定 的 文件 描述 符 。 这 意味 open 事件 不 再 会 触发 。 


如 果 options 是 一 个 字符 串 ， 那 么 它 表 示 指 定 的 编码 。 
Class: fs.WriteStream 


WriteStream 是 一 个 可 写 流 。 


Event: ‘open' 
e fd Integer writeStream 使 用 的 文件 描述 符 


当 可 写 流 文件 被 打开 时 触发 。 


file.bytesWritten 


至 今 为 止 写 入 的 字 节 数 。 不 包括 仍 在 写 入 队列 中 的 数据 。 


Class: fs.FSWatcher 


由 fs.watch() 返回 的 对 象 。 


watcher.close() 


停止 在 指定 的 fs. FSWatcher 上 监视 文件 变化 。 


Event: change- 


e event String 文件 的 改变 类 型 
e filename String The filename that changed (if relevant/available) 被 改变 的 文件 
(如 果 有 意义 /可 用 的 话 ) 


当 被 监视 的 目录 或 文件 发 生 了 改变 时 触发 。 详 情 参 阅 fs.watch 。 


Event: ‘error’ 


e error Error object 


当 错 误 发 生 时 触发 。 


Global Objects 


3% He xt Be PT A AKIRA AT FAY o FOP AQ He RR IE ES AE AA ” ae 
在 模块 作用 域内 - 它 将 会 在 文档 中 被 指出 。 
global 

e {Object} 全 局 命名 空间 对 象 。 
在 浏览 器 ， 顶 级 作用 域 是 全 局 作用 域 。 这 意味 着 在 浏览 器 的 全 局 作用 域 中 ， 你 创建 
了 一 个 对 象 那么 就 是 定义 了 一 个 全 局 对 象 。 在 node.js 中 是 不 同 的 ， 顶 级 作用 域 
不 是 全 局 作用 域 ， 在 node.js 的 模块 中 创建 的 对 象 只 属于 那个 模块 。 
process 

e {Object} 


进程 对 象 。 参 阅 process 章节 。 


console 
e {Object} 


被 用 来 向 stdout 和 stderr 打印 信息 。 参 阅 console 章节 。 


Class: Buffer 
e {Function} 


被 用 来 处 理 二 进 制 数据 9 参阅 buffer 章节 o 


require() 
e {Function} 


用 来 引入 模块 。 参 阅 Modules 章节 。 require 实际 上 不 是 全 局 的 ， 而 是 每 个 模 
块 本 地 的 。 


require.resolve() 


使 用 内 部 require() 机 制 来 查找 模块 位 置 ， 但 是 只 返回 被 解析 的 模块 路 径 ， 而 不 
是 加 载 模块 。 
require.cache 
e Object 
GAR IRR ART > BRERA APRA o MIMS RN Fa] 
入 会 重新 加 载 模块 。 
require.extensions 
稳定 度 : 0 - FA 
e Object 
指示 require 方法 如 何 处 理 特定 的 文件 扩展 名 。 


将 扩展 名 为 .sjs 的 文件 当做 ,js 文件 处 理 : 


require.extensions['.sjs'] = require.extensions['.js']; 


在 被 弃 用 之 前 ， 这 个 列表 被 用 于 按 需 编译 非 JavaScript 模块 并 加 载 
A node.js 。 但 是 ， 在 实践 中 ， 有 更 好 地 方法 来 实现 这 个 功能 ， 如 使 用 其 他 
的 node.js 程序 来 加 载 模块 ， 或 在 预 编译 为 JavaScript ° 


由 于 模块 系统 的 API 已 被 锁定 ， 这 个 特性 可 能 永远 不 会 被 去 处 。 但 是 它 可 能 有 细微 
的 bug 和 额外 的 复杂 性 ， 所 以 最 好 不 要 再 使 用 它 。 
__ filename 

e {String} 


当前 被 指定 的 代码 的 文件 名 。 它 被 解析 为 绝对 路 径 。 对 于 主 程序 ， 它 可 能 与 命令 行 
中 使 用 的 文件 路 径 是 不 同 的 。 在 模块 内 这 个 值 是 该 模块 文件 的 路 径 。 


例子 : 在 /Users/mjr 目录 中 执行 iojs example.js 


console.log(__filename); 


// /Users/mjr/example.js 


_ filename 实际 上 不 是 全 局 的 ， 而 是 每 个 模块 本 地 的 。 


__ dirname 
e {String} 
当前 执行 脚本 所 在 的 目录 名 。 


例子 :在 /Users/mjr 目录 中 执行 iojs example.js 


console.log(__dirname); 


// /Users/mjr 


_ dirname 实际 上 不 是 全 局 的 ， 而 是 每 个 模块 本 地 的 。 


module 
e {Object} 


当前 模块 的 一 个 引用 。 特 别 的 ， module.exports 被 用 来 指定 模块 需要 对 外 暴露 
的 东西 ， 这 些 东 西 可 以 通过 require() 取得 。 


module 实际 上 不 是 全 局 的 ， 而 是 每 个 模块 本 地 的 。 


更 多 信息 请 参阅 模块 系统 文档 。 


exports 


module.exports 的 一 个 快捷 引用 。 对 于 何 时 使 用 exports ， 何 时 使 
用 module.exports ， 请 参阅 模块 系统 文档 。 


exports 实际 上 不 是 全 局 的 ， 而 是 每 个 模块 本 地 的 。 
更 多 信息 请 参阅 模块 系统 文档 。 


更 多 信息 请 参阅 module 章节 。 


setTimeout(cb, ms) 


在 至 少 ms BAG > TAA BR ch 。 实 际 的 延 时 依赖 于 外 部 因素 ， 如 操作 系统 
的 定时 器 粒度 和 系统 负载 。 


超时 时 间 必 须 在 1 到 2,147,483,647 之 间 。 如 果 超 过 了 这 个 范围 ， 它 会 被 重 置 为 1 毫 
秒 。 换 名 话说 ， 定 时 器 的 跨度 不 可 以 超过 24.8 天 。 


返回 一 个 代表 此 定时 器 的 句柄 值 。 


clearTimeout(t) 


停止 一 个 之 前 通过 setTimeout() 创建 的 定时 器 。 它 的 回调 函数 将 不 会 执行 。 


setinterval(cb, ms) 


以 ms 毫秒 的 间隔 ， 重 复 地 执行 回调 函数 cb 。 实 际 的 间隔 可 能 会 有 浮动 ， 这 取决 
于 外 部 因素 ， 如 操作 系统 的 定时 器 粒度 和 系统 负载 。 它 永远 不 会 比 ms 短 只 会 比 它 
长 o 


间隔 值 必 须 在 1 到 2,147,483,647 之 间 。 如 果 超 过 了 这 个 范围 ， 它 会 被 重 置 为 1 毫 
秒 。 换 名 话说， 定时 器 的 跨度 不 可 以 超过 24.8 天 。 


返回 一 个 代表 此 定时 器 的 句柄 值 。 


clearInterval(t) 
停止 一 个 之 前 通过 setInterval() 创建 的 定时 器 。 它 的 回调 函数 将 不 会 执行 。 


定时 器 函数 都 是 全 局 变量 。 参 阅 定时 器 章节 。 


HTTP 


稳定 度 : 2 -稳定 
你 必须 通过 require('http') 来 使 用 HTTP 服 务 器 和 客户 端 。 


node.js 中 的 HTTP 接 口 被 设置 来 支持 许多 HTTP 协 议 里 原本 用 起 来 很 困难 的 特 
性 。 特 别 是 大 且 成 块 的 有 编码 的 消息 。 这 个 接口 从 不 缓冲 整个 请 求 或 响应 。 用 户 可 
以 对 它们 使 用 流 。 


HTTP 消 息 头 可 能 是 一 个 类 似 于 以 下 例子 的 对 象 : 


{ 'content-length': '123', 
'content-type': 'text/plain', 
‘connection': 'keep-alive', 
"host": 'mysite.com', 
accepts 737") + 


键 是 小 写 的 。 值 没有 被 修改 。 


为 了 全 方位 的 支持 所 有 的 HTTP 应 用 。 node.js 的 HTTP API 是 非常 底层 的 。 它 只 
处 理 流 以 及 解释 消息 。 它 将 消息 解释 为 消息 头 和 消息 体 ， 但 是 不 解释 实际 的 消息 头 
和 消息 体 。 


被 定义 的 消息 头 允 许 以 多 个 ， 字 符 分 割 ， 除 了 set-cookie 和 cookie 头 ， 因 为 
它们 表示 值得 数组 。 如 content-length 这 样 只 有 单个 值 的 头 被 直接 将 解析 ， 并 
且 成 为 解析 后 对 象 的 一 个 单 值 。 


收 到 的 原始 消息 头 会 被 保留 在 rawHeaders 属性 中 ， 它 是 一 个 形式 如 [key, 
value, key2, value2, ...] 的 数组 。 例 如 ， 之 前 的 消息 头 可 以 有 如 下 
的 rawHeaders 


[ 'ConTent-Length', '123456', 
“content “BENGTH '123', 
'content-type', ‘text/plain', 
'CONNECTION', 'keep-alive', 
'Host', 'mysite.com', 
AEEA /ond 


http.METHODS 

e Array 
一 个 被 解析 器 所 支持 的 HTTP 方 法 的 列表 。 
http.STATUS CODES 

e Object 
一 个 所 有 标准 HTTP 响 应 状态 码 的 集合 ， 以 及 它们 的 简短 描述 。 例 
如 ， http.STATUS CODES[404] === 'Not Found' ° 
http.createServer([requestListener]) 

e 返回 一 个 新 的 http.Server 实例 


requestListener 是 一 个 会 被 自动 添加 为 request 事件 监听 器 的 函数 。 


http.createClient([port][, host]) 


这 个 函数 已 经 被 启用 。 请 使 用 http.request() 替代 。 构 造 一 个 新 的 HTTP 客 户 
端 。 port 和 host 指定 了 需要 连接 的 目标 服务 器 。 


Class: http.Server 


这 是 一 个 具有 以 下 事件 的 EventEmitter 


Event: ‘request' 


e function (request, response) { } 


当 有 请 求 来 到 时 触发 。 注 意 每 一 个 连接 可 能 有 多 个 请 求 (在 长 连接 的 情况 下 ) 。 请 
求 是 一 个 http.IncomingMessage 实例 ， 响 应 是 一 个 http.ServerResponse 实 
例 o 


Event: ‘connection’ 


e function (socket) { } 
当 一 个 新 的 TCP 流 建立 时 触发 。 socket 是 一 个 net.Socket 类 型 的 实例 。 用 户 
通常 不 会 接触 这 个 事件 。 特 别 的 ， 因 为 协议 解释 器 绑 定 它 的 方式 ， socket 将 不 会 
触发 readable 事件 。 这 个 socket 可 以 由 request.connection 得 到 。 
Event: ‘close’ 

e function () {} 


当 服 务 器 关闭 时 触发 。 


Event: ‘'checkContinue’ 
e function (request, response) { } 


ce Se Expect: 100-continue 请 求 时 触发 。 如 果 不 监听 这 个 事 
件 ， 那 么 服务 器 会 酌情 自动 响应 一 个 100 Continue 。 


处 理 该 事件 时 ， 如 果 客 户 端 可 以 继续 发 送 请 求 主体 则 调 
用 response.writeContinue() ， 如 果 不 能 则 生成 合适 的 HTTP 响 应 (如 400 
Bad Request ) ° 


注意 ， 当 这 个 事件 被 触发 并 且 被 处 理 ， request 事件 则 不 会 再 触发 。 


Event: connect' 
e function (request, socket, head) { } 


每 当 客户 端 发 起 一 个 http CONNECT 请 求 时 触发 。 如 果 这 个 事件 没有 被 监听 ， 那 么 
客户 端 发 起 http CONNECT 的 连接 会 被 关闭 。 


e request 是 一 个 http 请 求 参 数 ， 它 也 被 包含 在 request 事件 中 。 
e socket 是 一 个 服务 器 和 客户 端 间 的 网 络 套 接 字 。 
e head 是 一 个 Buffer 实例 ， 隧 道 流 中 的 第 一 个 报 文 ， 该 参数 可 能 为 空 


在 这 个 事件 被 触发 后 ， 请 求 的 socket 将 不 会 有 data 事件 的 监听 器 ， 意 味 着 你 
将 要 绑 定 一 个 data 事件 的 监听 器 来 处 理 这 个 socket 中 发 往 服务 器 的 数据 。 
Event: ‘upgrade' 

e function (request, socket, head) { } 


每 当 客 户 端 发 起 一 个 http upgrade 请 求 时 触发 。 如 果 这 个 事件 没有 被 监听 ， 那 么 
客户 端 发 起 upgrade 的 连接 会 被 关闭 。 


e request 是 一 个 http 请 求 参 数 ， 它 也 被 包含 在 request 事件 中 。 
e socket 是 一 个 服务 器 和 客户 端 间 的 网 络 套 接 字 。 
e head 是 一 个 Buffer 实例 ， 升 级 后 流 中 的 第 一 个 报 文 ， 该 参数 可 能 为 空 


在 这 个 事件 被 触发 后 ， 请 求 的 socket 将 不 会 有 data 事件 的 监听 器 ， 意 味 着 你 
将 要 绑 定 一 个 data 事件 的 监听 器 来 处 理 这 个 socket 中 发 往 服务 器 的 数据 。 
Event: ‘clientError’ 

e function (exception, socket) { } 
如 果 一 个 客户 端 连 接 发 生 了 错误 ， 这 个 事件 将 会 被 触发 。 


socket 是 一 个 错误 来 源 的 net .Socket Fe 


server.listen(port[, hostname][, backlog][, callback]) 


从 指定 的 端 口 和 主机 名 开始 接收 连接 o 如果 hostname 被 忽略 那么 如 果 IPv6 可 
用 ， 服 务 器 将 接受 任意 IPv6 地 址 (::) ， 否 则 为 任何 IPv4 地 址 
(0.0.0.) 。 port 为 o 将 会 设置 一 个 随机 端口 。 


如 果 要 监听 一 个 unix socket ， 请 提供 一 个 文件 名 而 不 是 端口 和 主机 名 。 


backlog 是 连接 等 待 队列 的 最 大 长 度 。 它 的 实际 长 度 将 有 你 操作 系统 
的 sysctl 设置 (如 linux 中 的 tcp_max_syn_backlog 和 somaxconn ) 决定 。 默 
认 值 为 511 (不 是 512 ) 。 


这 个 函数 式 异 步 的 。 最 后 一 个 callback 参数 将 会 添加 至 listening 事件 的 监听 
Zo A] net.Server.listen(port) ° 


server.listen(path[, callback]) 


2, 


通过 给 定 的 path ， 开 启 一 个 监听 连接 的 UNIX socket 服务 器 。 


这 个 函数 式 蜡 步 的 。 最 后 一 个 callback 参数 将 会 添加 至 listening 事件 的 监听 


Z ° Ağ] net.Server.listen(path) ° 


Eòs 


server.listen(handle[, callback]) 


e handle Object 
e callback Function 


handle 对 象 是 既 可 以 是 一 个 server 可 以 是 一 个 socket (或 者 任意 以 下 划 线 开头 
的 成 员 handle ) ， 或 一 个 {fd: <n>} 对 象 。 


这 将 使 得 服务 器 使 用 指定 猛 柄 接受 连接 ， 但 它 假 设 文 件 描述 符 或 甸 柄 已 经 被 绑 定 
指定 的 端口 或 域名 socket 。 


在 Windows 下 不 支持 监听 一 个 文件 描述 符 。 

个 函数 式 异 步 的 。 最 后 一 个 callback 参数 将 会 添加 至 listening 事件 的 监听 
z 。 参 阅 net.Server.listen() ° 
server.close([callback]) 


让 服务 器 停止 接收 新 的 连接 。 参 阅 net.Server.close() ° 


server.maxHeadersCount 


限制 最 大 请 求 头 数 量 ， 默 认为 1000 。 如 果 设 置 为 9 ， 则 代表 无 限制 。 


server.setTimeout(msecs, callback) 


e msecs Number 
e callback Function 


设置 socket 的 超时 值 ， 并 且 如 果 超 时 ， 会 在 服务 器 对 象 上 触发 一 个 timeout # 
件 ， 并 且 将 传递 socket 作为 参数 。 

如 果 在 服务 器 对 象 时 又 一 个 timeout 事件 监听 器 ， 那 么 它 将 会 被 调用 ， 而 超时 
的 socket 将 会 被 作为 参数 。 


默认 的 ， 服 务 器 的 超时 值 是 两 分 钟 ， 并 且 如 果 超 时 ， socket SRA WAR {2 
是 ， 如 果 你 给 timeout 事件 传递 了 回调 函数 ， 那 么 你 必须 为 要 杂 自 处 
理 socket 超时 。 


返回 一 个 server 对 象 。 


server.timeout 
e Number 默认 为 120000 (两 分 钟 ) 


一 个 socket 被 判定 为 超时 之 前 的 毫秒 数 。 


is 


注意 ， socket 的 超时 逻辑 在 连接 时 被 设 定 ， 所 以 改变 它 的 值 仅 影响 之 后 到 达 服 务 
的 连接 ， 而 不 是 所 有 的 连接 。 
置 为 0 


将 会 为 连接 禁用 所 有 的 自动 超时 行为 。 


Class: http.ServerResponse 


这 个 对 象 由 HTTP 服 务 器 内 部 创建 ， 而 不 是 由 用 户 。 它 会 被 传递 给 request 事件 
监听 器 的 第 二 个 参数 。 


这 个 对 象 实现 了 writable 流 接口 。 它 是 一 个 具有 以 下 事件 的 EventEmitter 


Event: ‘close’ 


e function () {} 


表明 底层 的 连接 在 response.end() 被 调用 或 能 够 冲刷 前 被 关闭 。 
Event: ‘finish’ 
e function () {} 


当 响 应 被 设置 时 触发 。 更 明确 地 说 ， 这 个 事件 在 当 响 应 头 的 最 后 一 段 和 响应 体 为 了 
网 络 传输 而 交 给 操作 系统 时 触发 。 它 并 不 表明 客户 端 已 经 收 到 了 任何 信息 。 


这 个 事件 之 后 ， response 对 象 不 会 再 触发 任何 事件 。 


response.writeContinue() 


给 客户 端 传递 一 个 HTTP/1.1 100 Continue 信息 ， 表 明 请 求 体 必须 被 传递 。 参 阅 
服务 器 的 checkContinue 事件 。 


response.writeHead(statusCode[, statusMessagel]l, 
headers]) 


为 请 求 设 置 一 个 响应 头 。 statusCode 是 一 个 三 位 的 HTTP 状 态 码 ， 如 404 。 最 
后 一 个 参数 headers ， 是 响应 头 。 第 二 个 参数 statusMessage 是 可 选 的 ， 表 示 
状态 码 的 一 个 可 读 信息 


例子 : 


var body = 'hello world'; 

response.writeHead(200, { 
'Content-Length': body.length, 
'Content-Type': 'text/plain' }); 


这 个 方法 对 于 一 个 信息 只 能 调用 一 次 ， 并 且 它 必须 在 response.end() 之 前 被 调 
用 。 


你 在 调用 这 个 方法 前 调用 了 response.write() 或 response.end() ， 将 会 
man Až > FHH—+ implicit/mutable 头 会 被 计算 使 用 。 


注意 ， Content-Length 是 以 字 节 计 ， 而 不 是 以 字符 计 。 上 面 例子 能 正常 运行 时 


因为 字符 串 'hello world' 仅 包 含 单字 节 字 符 。 如 果 响 应 体 包 含 了 多 字 节 编码 的 
字符 ， 那 么 必须 通过 指定 的 编码 来 调用 Buffer.byteLength() 来 确定 字 节 数 。 并 


且 node.js 不 会 检查 Content-Length 与 响应 体 的 字 节 数 是 否 相等 。 


response.setTimeout(msecs, callback) 


e msecs Number 
e callback Function 


设置 socket 的 超时 值 (SA) ， 如 果 传递 了 回调 函数 ， 那 么 它 将 被 添加 
至 response 对 象 的 timeout 事件 的 监听 器 。 


p 果 没有 为 request ， 或 服务 器 添加 timeout H Z ° A 
A socket 会 在 超时 时 销毁 。 如 果 你 为 request > request 或 服务 器 添加 
了 timeout 监听 器， 那么 自 处 理 socket 超时 。 


返回 一 个 response 对 象 。 


response.statusCode 


当 使 用 隐 式 响应 头 (不 明确 调用 response.writeHead() ) 时 ， 这 个 属性 控制 了 
发 送 给 客户 端的 状态 码 ， 在 当 响 应 头 被 冲刷 时 。 


例子 : 


response.statusCode = 404; 
在 响应 头发 送 给 客户 端 之 后 ， 这 个 属性 表明 了 被 发 送 的 状态 码 。 


response.statusMessage 


当 使 用 隐 式 响应 头 (不 明确 调用 response.writeHead() ) 时 ， 这 个 属性 控制 了 
发 送 给 客户 端的 状态 信息 ， 在 当 响应 头 被 冲刷 时 。 当 它 没有 被 指定 
( undefined ) 时 ， 将 会 使 用 标准 HTTP 状 态 码 信息 。 


例子 : 


response.statusMessage = 'Not found ' ， 


在 响应 头发 送 给 客户 端 之 后 ， 这 个 属性 表明 了 被 发 送 的 状态 信息 。 


response.setHeader(name, value) 


为 一 个 隐 式 的 响应 头 设 置 一 个 单独 的 头 内 容 。 如 果 这 个 头 已 存在 ， 那 么 将 会 被 覆 
盖 。 当 你 需要 发 送 一 个 同名 多 值 的 头 内 容 时 请 使 用 一 个 字符 串 数 组 。 


例子 : 


response.setHeader("Content-Type", "text/html"); 


/ /Nr 
LAN 


response.setHeader("Set-Cookie", ["type=ninja", "language=javasc 
ript"]); 


response.headersSent 


布尔 值 (RE) 。 如 果 响 应 头 被 发 送 则 为 true ， 反 之 为 false 。 


response.sendDate 
3A true 时 ， 当 响应 头 中 没有 Date 值 时 会 被 自动 设置 。 默 认为 true 。 


个 值 只 会 为 了 测试 目的 才 会 被 禁用 。HTTP 协 议 要 求 响应 头 中 有 Date 值 。 


response.getHeader(name) 


读 取 已 经 被 排队 但 还 未 发 送 给 客户 端的 响应 头 。 注 意 name 是 大 小 写 敏 感 的 。 这 个 
况 数 只 能 在 响应 头 被 隐 式 冲刷 前 被 调用 。 


例子 : 


var contentType = response.getHeader('content-type'); 


response.removeHeader(name) 
取消 一 个 在 队列 中 等 待 隐 式 发 送 的 头 。 
例子 : 


response. removeHeader("Content -Encoding”) ， 


response.write(chunk[, encoding][, callback]) 


如 果 这 个 方法 被 调用 并 且 response.writeHead() 没有 备 调用 ， 那 么 它 将 转换 到 
隐 式 响应 头 模式 ， 并 且 刷 新 隐 式 响应 头 。 


这 个 方法 传递 一 个 数据 块 的 响应 体 。 这 个 方法 可 能 被 调用 多 次 来 保证 连续 的 提供 响 
应 体 。 


数据 块 可 以 是 一 个 字符 串 或 一 个 buffer 。 如 果 数 据 块 是 一 个 字符 事 ， 那 么 第 二 个 
eee 


注意 : 这 是 一 个 底层 的 HTTP 报 文 ， 高 级 的 多 部 分 报 文 编码 无 法 使 用 。 


第 一 次 调用 response.write() 时 ， 它 会 传递 缓存 的 头 信息 以 及 第 一 个 报 文 给 客 

户 端 。 第 二 次 调用 时 ， node.js 假设 你 将 发 送 数 据 流 ， 然 后 分 别 发 送 。 这 意味 着 

响应 式 缓冲 到 第 一 个 报 文 的 数据 块 中 。 

如 果 整 个 数据 都 成 功 得 冲刷 至 内 核 缓冲 ， 则 放 回 true 。 如 果 用 户 内 存 中 有 部 分 或 
全 部 的 数据 在 队列 中 ， 那 么 返回 false 。 drain 事件 将 会 在 缓冲 再 次 释放 时 触 

发 。 


response.addTrailers(headers) 


这 个 方法 添加 HTTP 尾 随 头 (一 个 在 消息 最 后 的 头 ) 给 响应 。 


只 有 当 数 据 编码 被 用 于 响应 时 尾随 才 会 触发 。 如 果 不 是 (如 请 求 是 HTTP/1.0 ) ， 
它们 将 被 安静 地 丢弃 。 


注意 ， 如 果 你 要 触发 尾随 消息 ，HTTP 要 求 传 递 一 个 包含 报 文 头 场 列表 的 尾随 头 : 


response.writeHead(200, { 'Content-Type': 'text/plain', 
‘Trailer’: "Content-MD5' }); 

response.write(fileData) ; 

response.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4 

bca667"}); 

response.end(); 


response.end([data][, encoding][, callback]) 


这 个 方法 告知 服务 器 所 有 的 响应 头 和 响应 体 都 已 经 发 送 ; 服务 器 会 认为 这 个 消息 完 
成 了 。 这 个 方法 必须 在 每 次 响应 完成 后 被 调用 。 


如 果 指 定 了 data ， 就 相当 于 调用 了 response.write(data, encoding) 之 后 再 
调用 response.end(callback) 。 


如 果 指 定 了 回调 函数 ， 那 么 它 将 在 响应 流 结束 后 触发 。 


http.request(options[, callback]) 


node.js 为 每 个 服务 器 维护 了 几 个 连接 ， 用 来 产生 HTTP 请 求 。 这 有 函数 允许 你 透 
明 地 发 送 请 求 。 


options 参数 可 以 是 一 个 对 象 或 一 个 字符 串 ， 如 果 options 是 一 个 字符 串 ， 它 
将 自动 得 被 url.parse() 翻译 。 


Options: 


e host: 一 个 将 要 向 其 发 送 请 求 的 服务 器 域名 或 |P 地 址 。 默 认为 localhost 。 
e hostname: host 的 别名 。 为 了 支持 url.parse() 的 
话 ， hostname 比 host 更 好 些 。 
e family: 解析 host 和 hostname 时 的 IP 地 址 协议 族 。 合 法 值 是 4 和 6 。 当 
没有 指定 时 ， 将 都 被 使 用 。 
o port: 远程 服务 器 端口 。 默 认为 80 ° 
e localAddress: 用 于 绑 定 网 络 连接 的 本 地 端口 。 
e socketPath: Unix 域 socket (使 用 host:port 或 socketPath ) ° 
e method: 指定 HTTP 请 求 方 法 的 字符 串 。 默 认为 GET 。 
e path: 请 求 路 径 。 默 认为 / 。 如 果 有 查询 字符 串 ， 则 需要 包含 。 例 
如 '/index.html?page=12'。 请 求 路 径 包 含 非法 字符 时 抛 出 异常 。 目 前 ， 只 否决 
空格 ， 不 过 在 未 来 可 能 改变 。 
e headers: 一 个 包含 请 求 头 的 对 象 。 
e auth: 用 于 计算 认证 头 的 基本 认证 ， 即 'user:password' ° 
agent: 控制 agent 行为 。 当 使 用 一 个 代理 时 ， 请 求 将 默认 为 Connection: 
keep-alive 。 可 能 值 有 : 
o undefined (RU): 在 这 个 主机 和 端口 上 使 用 全 局 ‘agent。 
o Agent object: Æ agent 中 显示 使 用 passed ° 
o false: 跳出 agent 的 连接 池 。 默 认 请 求 为 Connection: close ° 


可 选 的 回调 函数 将 会 被 添加 为 response 事件 的 “一 次 性 "监听 器 (one time 
listener) 。 


http.request() 返回 一 个 http.ClientRequest 类 的 实例 。 这 
个 ClientRequest 实例 是 一 个 可 写 流 。 如 果 你 需要 使 用 POST 请 求 上 传 一 个 文 
件 ， 那 么 就 将 之 写 入 这 个 ClientRequest It% ° 


例子 : 


var postData = querystring.stringify({ 
'msg' : ‘Hello World!' 
}); 


var options = { 
hostname: 'www.google.com', 
port: 80, 
path: '/upload', 
method: 'POST', 
headers: { 
"Content-Type': ‘application/x-www-form-urlencoded', 
"Content-Length': postData.length 
} 
}; 


var req = http.request(options, function(res) { 
console.log('STATUS: ' + res.statusCode); 
console.log('HEADERS: ' + JSON.stringify(res.headers) ); 
res.setEncoding('utf8'); 
res.on('data', function (chunk) { 
console.log('BODY: ' + chunk); 
+); 
res.on('end', function() { 
console.log('No more data in response.') 
}) 
}); 


req.on('error', function(e) { 
console.log('problem with request: ' + e.message); 


PO) 


// write data to request body 
req.write(postData); 
req.end(); 


注意 ， 在 例子 中 调用 了 req.end() 。 使 用 http,request() 时 必须 调 
用 req.end() 来 表明 你 已 经 完成 了 请 求 (即使 没有 数据 要 被 写 入 请 求 体 ) © 


oe oe TCP 级 别 错误 或 实际 的 HTTP 解 析 错 
误 ) ， 一 个 error 事件 将 会 在 返回 对 象 上 能 发 。 

下 面 有 一 些 特 殊 的 需要 主要 的 请 求 头 : 

发 送 'Connection: keep-alive' 会 告知 node.js 保持 连 直 到 下 一 个 请 求 
发 送 。 


e Ask 'Content-length' 头 会 禁用 默认 的 数据 块 编码 。 


o 发 送 'Expect' 头 将 会 立刻 发 送 一 个 请 求 头 。 通 常 ， 当 发 送 'Expect: 100- 
continue' 时 ， 你 需要 同时 设置 一 个 超时 和 监听 后 续 的 时 间 。 参 阅 RFC2616 
的 8.2.3 章 节 来 获取 更 多 信息 。 


© 发 送 一 个 授权 头 将 会 覆盖 使 用 auth 选项 来 进行 基本 授权 


http.get(options[, callback]) 


由 于 大 多 数 请 求 是 没有 请 求 体 的 GET 请 求 。 node.js 提供 了 这 个 简便 的 方法 。 
这 个 方法 和 http.request() 方法 的 唯一 区 别 是 它 设置 请 求 方法 为 GET 且 自 动 调 
用 req.end() ° 


例子 : 


http.get("http://www.google.com/index.html", function(res) { 


console.log("Got response: " + res.statusCode); 
}).on(‘'error', function(e) { 

console.log("Got error: " + e.message); 
}); 


Class: http.Agent 
HTTP Agent 是 用 来 把 HTTP 客 户 端 请 求 中 的 socket 做 成 池 。 


HTTP Agent 也 把 客户 端的 请 求 默 认为 使 用 Connection:keep-alive 。 如 果 没 有 
HTTP 请 求 正在 等 待 成 为 空闲 的 套 接 字 的 话 ， 那 么 套 接 字 将 关闭 。 这 意味 

着 node.js 的 资源 池 在 负载 的 情况 下 对 keep-alive 有 利 ， 但 是 仍然 不 需要 开发 
人 员 使 用 KeepAlive 来 手动 关闭 HTTP 客 户 端 。 


如 果 你 选择 使 用 HTTP KeepAlive ， 那 么 你 可 以 创建 一 个 标志 设 为 true Agent 
对 象 ( 见 下 面 的 构造 函数 选项 ) 。 然 后 ，Agent 将 会 在 资源 池 中 保持 未 被 使 用 的 套 
接 字 ， 用 于 未 来 使 用 。 它 们 将 会 被 显 式 标记 ， 以 便于 不 保持 node.js 进程 的 运 
行 。 但 是 当 KeepAlive agent 没 有 被 使 用 时 ， 显 式 地 destroy() KeepAlive agent 
仍然 是 个 好 主意 ， 这 样 socket 会 被 关闭 。 


当 socket 触发 了 close 事件 或 者 特殊 的 agentRemove 事件 的 时 候 ， 套 接 字 们 
从 agent 的 资源 池 中 移 除 。 这 意味 着 如 果 你 打算 保持 一 个 HTTP 请 求 长 时 间 开 启 ， 并 
且 不 希望 它 保持 在 资源 池 中 ， 那 么 你 可 以 按照 下 列 几 行 的 代码 做 事 : 


http.get(options, function(res) { 
M OO. Suh 

}).on("socket", function (socket) { 
socket.emit("agentRemove"); 


}); 


另外 ， 你 可 以 使 用 agent:false XFA XW : 


http.get({ 

hostname: 'localhost', 

port: 80, 

path: 7 =; 

agent: false // create a new agent just for this one request 
i; function, (res): 4 

// Do stuff with response 


}) 


new Agent([options])# 
options Object 为 agent 设 置 可 配置 的 选项 。 可 以 有 以 下 属性 : 


e keepAlive Boolean 在 未 来 保持 池 中 的 socket 被 其 他 请 求 所 使 用 ， 默 认 
为 false 

e keepAliveMsecs Integer 当 使 用 HTTP KeepAlive 时 ， 通 过 被 保持 连接 
的 socket 发 送 TCP KeepAlive 报 文 的 问 隔 。 默 认为 1000 ° A 
在 KeepAlive 被 设置 为 true 时 有 效 

e maxSockets Number 每 个 主机 允许 拥有 的 socket 的 最 大 数量 。 默 认 
为 Infinity 


e maxFreeSockets Number 在 空闲 状态 下 允许 打开 的 最 大 socket 数 。 仅 
在 keepAlive A true 时 有 效 。 默 认为 256 


http.request 使 用 的 默认 的 http.globalAgent 包含 它们 属性 的 各 自 的 默认 
值 。 


为 了 配置 它们 中 的 任何 一 个 ， 你 必须 创建 你 自己 的 Agent 对 象 。 


var http = require('http'); 

var keepAliveAgent = new http.Agent({ keepAlive: true }); 
options.agent = keepAliveAgent; 

http.request(options, onResponseCallback); 


agent.maxSockets 

默认 为 Infinity 。 决 定 了 每 个 源 上 可 以 拥有 的 并 发 的 socket 的 数量 。 源 

为 'host:port' 或 'host:port:localAddress' 结合 体 。 
agent.maxFreeSockets 

默认 为 256 。 对 于 支持 HTTP KeepAlive 的 Agent， 这 设置 了 在 空闲 状态 下 保持 打 
开 的 最 大 socket 数量 。 

agent.sockets 


这 个 对 象 包 含 了 正在 被 Agent 使 用 de socket 数组 。 请 不 要 修改 它 。 


agent.freeSockets 

这 个 对 象 包含 了 当 HTTP KeepAlive 被 使 用 时 正在 等 待 的 socket 数组 。 请 不 要 修 
改 它 。 

agent.requests 


这 个 对 象 包含 了 还 没有 被 分 配给 socket 的 请 求 队 列 。 请 不 要 修改 它 。 


agent.destroy() 


SL sE  hagentt® MAMA socket 。 


通常 没有 必要 这 么 做 。 人 但是， 如果 你 正在 使 用 一 个 启用 了 KeepAlive “Jagent> 4% 
ee 它 不 会 再 被 使 有 用时。 否则， 在 服务 器 关闭 它们 
前 socket 可 能 被 闲置 


agent.getName(options) 


通过 一 个 请 o a 无 二 的 名 字 ， 来 决定 一 个 连接 是 否 可 被 再 使 
用 。 在 http 代 理 中 ， 这 返回 host:port:localAddress 。 在 https 代 理 

中 ， name ees > cert > ciphers? HTTPS/TLS-specific 配置 来 决定 一 

个 socket 是 否 能 被 再 使 用 。 


http.globalAgent 


所 有 的 http 客 户 端 请 求 使 用 的 默认 全 局 Agent 实例 。 


Class: http.ClientRequest 


这 个 对 象 时 被 内 部 创建 的 ， 并 且 通 过 TE request() 被 返回 。 它 代表 了 一 个 正 
在 处 理 的 请 求 ， 其 头 部 已 经 进入 了 队列 。 这 个 头 部 仍然 可 以 通 

过 setHeader (name, 

value) > getHeader(name) 和 removeHeader(name) 修改 。 实 际 的 头 部 会 随 


着 第 一 个 数据 块 发 送 ， 或 在 关闭 连接 时 发 送 
要 获得 响应 对 象 ， 请 为 response pe ee ° request 对 象 


的 response 事件 将 会 在 收 到 响应 头 时 触发 。 这 个 response 事件 的 第 一 个 参数 
是 一 个 http.IncomingMessage 的 实例 。 


在 response 事件 期 间 ， 可 以 给 响应 对 象 添 加 监听 器 ; 尤其 是 监听 data 事件 。 


果 没 有 添加 response 事件 监听 器 ， 那 么 响应 会 被 完全 和 忽略。 但是， 如 果 你 添加 
J response 事件 ， 那 么 你 必须 通过 调用 response,read() ， 添 加 data 事件 
监听 器 或 调用 ,resume() 方法 等 等 ， 来 从 响应 对 象 中 消耗 数据 。 在 数据 被 消费 之 
前 ， end 事件 不 会 触发 。 如 果 数 据 没 有 被 读 取 ， 它 会 消耗 内 存 ， 最 后 导 
致 'process out of memory! 错误 。 


注意 : node.js 不 会 检查 Content-Length 和 被 传输 的 响应 体 长 度 是 否 相 同 。 


E 


这 个 请 求实 现 了 writable 流 接口 。 这 是 一 个 包含 了 以 下 事件 
的 EventEmitter 


Event: ‘response’ 


e function (response) { } 


当 这 个 请 求 收 到 一 个 响应 时 触发 。 这 个 事件 只 会 被 触发 一 次 。 response 参数 是 一 


个 http.IncomingMessage 实例 。 


e Options: 
o host: 一 个 向 其 发 送 请 求 的 服务 器 的 域名 或 |P 地 址 
o port: 远程 服务 器 的 端口 
o socketPath: Unix 域 socket (使 用 host:port 或 socketPath 中 的 一 
个 ) 


Event: 'socket' 


e function (socket) { } 


4— socket 被 分 配给 一 个 请 求 时 触发 。 


Event: 'connect' 


e function (response, socket, head) { } 


每 次 服务 器 使 用 CONNECT 方法 响应 一 个 请 求 时 触发 。 如 果 这 个 事件 没有 被 监听 ， 
那么 接受 CONNECT 方法 的 客户 端 将 会 关闭 它们 的 连接 。 


以 下 是 一 对 客户 端 /服务 器 代码 ， 展 示 如 何 监 听 connect 事件 。 


var http = require('http'); 
var net = require('net'); 
var url = require('url'); 


// Create an HTTP tunneling proxy 

var proxy = http.createServer(function (req, res) { 
res.writeHead(200, {'Content-Type': 'text/plain'}); 
res.end('okay'); 

}); 

proxy.on('connect', function(req, cltSocket, head) { 
// connect to an origin server 
var srvUrl = url.parse('http://' + req.url); 
var srvSocket = net.connect(srvUrl.port, srvUrl.hostname, func 


CELOMO A 


cltSocket.write('HTTP/1.1 200 Connection Established\r\n' + 


'Proxy-agent: node.js-Proxy\r\n' + 
ENC NI 
srvSocket.write(head) ; 
srvSocket.pipe(cltSocket ); 
cltSocket.pipe(srvSocket); 
+); 
+); 


// now that proxy is running 
proxy.listen(1337, '127.0.0.1', Funct lon { 


// make a request to a tunneling proxy 
var options = { 

port: 1337, 

hostname: '127.0.0.1', 

method: 'CONNECT', 

path: 'www.google.com:80' 


+; 


var req = http.request(options); 
req.end(); 


req.on('connect', function(res, socket, head) { 
console.log('got connected!'); 


// make a request over an HTTP tunnel 
socket.write('GET / HTTP/1.1\r\n' + 
"Host: www.google.com:80\r\n' + 
"Connection: close\r\n' + 
AIEA 
socket.on('data', function(chunk) { 
console.log(chunk.toString()); 
}); 
socket.on('end', function() { 
proxy.close(); 
}); 
}); 
}); 


Event: 'upgrade" 


e function (response, socket, head) { } 


Emitted each time a server responds to a request with an upgrade. If this event 
isn't being listened for, clients receiving an upgrade header will have their 
connections closed. 每 次 服务 器 返回 upgrade 响应 给 请 求 时 触发 。 如 果 这 个 事件 
没有 被 监听 ， 客 户 端 接 收 一 个 upgrade 头 时 会 关闭 它们 的 连接 。 


以 下 是 一 对 客户 端 /服务 器 代码 ， 展 示 如 何 监听 upgrade 事件 。 
var http = require('http'); 


// Create an HTTP server 

var srv = http.createServer(function (req, res) { 
res.writeHead(200, {'Content-Type': 'text/plain'}); 
res.end('okay'); 

}); 

srv.on('upgrade', function(req, socket, head) { 
socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' 


'Upgrade: WebSocket\r\n' + 
"Connection: Upgrade\r\n' + 
Mie 


socket.pipe(socket); // echo back 


}); 


// now that server is running 
srv.listen(1337, '127.0.0.1', function() { 


// make a request 
var options = { 
port: 1337, 
hostname: '127.0.0.1', 
headers: { 
'Connection': 'Upgrade', 
'Upgrade': 'websocket' 


}; 


var req = http.request(options); 
req.end(); 


req.on('upgrade', function(res, socket, upgradeHead) { 
console.log('got upgraded!'); 
socket.end(); 
process.exit(0); 
+); 
}); 


Event: ‘continue’ 


e function () {} 


当 服 务 器 发 出 一 个 '100 Continue' HTTP 响 应 时 ， 通 常 这 是 因为 请 求 包 


日 


& 'Expect: 100-continue' 。 这 是 一 个 客户 端 须要 发 送 请 求 体 的 指示 。 


Event: ‘abort’ 
e function () {} 


当 请 求 被 客户 端 中 止 时 触发 。 这 个 事件 只 会 在 第 一 次 调用 abort() 时 触发 。 


request.flushHeaders() 
冲刷 请 求 头 。 


由 于 效率 原因 ， node.js 通常 在 直到 你 调用 request.end() 或 写 入 第 一 个 数据 
块 前 都 会 缓冲 请 求 头 ， 然 后 努力 将 请 求 头 和 数据 打包 为 一 个 TCP 报 文 。 


这 通常 是 你 想 要 的 〈 它 节约 了 一 个 TCP 往 返 ) 。 但 当 第 一 份 数据 会 等 待 很 久 才 被 发 
送 时 不 是 。 request.flushHeaders() 使 你 能 绕 过 这 个 优化 并 且 启 动 请 求 。 


request.write(chunk[, encoding][, callback]) 


发 送 一 个 响应 块 。 当 用 户 想 要 将 请 求 体 流 式 得 发 送 给 服务 器 时 ， 可 以 通过 调用 这 个 
方法 多 次 来 办 到 -- 在 这 种 情况 下 ， 建 议 在 创建 请 求 时 使 用 ['Transfer- 
Encoding', 'chunked'] 头 。 


chunk 参数 必须 是 一 个 Buffer 或 一 个 字符 串 。 
encoding 参数 是 可 选 的 ， 并 且 仅 当 chunk 是 字符 串 时 有 效 。 默 认为 'utf8' © 


callback 参数 是 可 选 的 ， 并 且 当 数据 块 被 冲刷 时 被 调用 。 


request.end([{data][, encoding][, callback]) 


结束 发 送 请 求 。 如 果 有 任何 部 分 的 请 求 体 未 被 发 送 ， 这 个 函数 将 会 将 它们 冲刷 至 流 
中 。 如 果 请 求 是 成 块 的 ， 它 会 发 送 终结 符 '9NrNnNrNn' e 


如 果 data 被 指定 ， 那 么 这 与 调用 request.write(data, encoding) 后 再 调 
用 request.end(callback) 相同 。 


如 果 callback 被 指定 ， 那 么 它 将 在 请 求 流 结束 时 被 调用 。 


request.abort() 


中 止 请 求 。 


request.setTimeout(timeout[, callback]) 


» 


一 旦 一 个 socket 被 分 配给 这 个 请 求 并 且 完 成 连接 ， socket.setTimeout() 
被 调用 。 


返回 request 对 象 。 


request.setNoDelay([noDelay]) 


内 


一 旦 一 个 socket 被 分 配给 这 个 请 求 并 且 完 成 连接 ， socket.setNoDelay() 
被 调用 。 


request.setSocketKeepAlive([enable][, initialDelay]) 


一 旦 一 个 socket 被 分 配给 这 个 请 求 并 且 完 成 连 


接 ， socket.setKeepAlive() 会 被 调用 。 


http.IncomingMessage 


一 个 IncomingMessage 对 象 被 http.Server 或 http.ClientRequest 创建 ， 


并 且 分 别 被 传递 给 request 和 response 事件 的 第 
状态 ， 响 应 头 和 响应 体 。 


它 实现 了 Readable 流 接 口 ， 并 且 有 以 下 额外 的 事件 ， 方 法 和 属性 。 


Event: ‘close’ 


e function () {} 


一 个 参数 。 它 被 用 来 取得 响应 


表明 底层 连接 被 关闭 。 与 end 相同 ， 这 个 时 间 每 次 响应 只 会 触发 一 次 。 


message.httpVersion 


当 To ， 客 户 端 发 送 的 HTTP 版 本 。 向 客户 端 发 送 


响应 的 HTTP 版 本 。 通 常 是 '1.1' 或 '1.0' 。 
另外 ， response.httpVersionMajor 是 第 一 个 整 
数 ，response.httpVersionMinor 是 第 二 个 整数 。 
message.headers 

请 求 /响应 头 对 象 。 


只 读 的 头 名 称 和 值 映射 。 头 名 称 是 小 写 的 ， 例 子 


// Prints something like: 

/7/ 4 ‘user-agent’: ‘curl/7.22.0", 
MOSiey a eel2 a0 Ones | SOOOkr 

2 accept a) ion 


console. Apacs headers); 


message.rawHeaders 


接受 到 的 原始 请 求 /响应 头 列表 。 


注意 键 和 值 在 同一 个 列表 中 ， 它 并 非 一 个 元 组 列表 。 于 是 ， 偶 数 偏 移 量 


偏 移 量 为 对 应 的 值 。 


响应 时 ， 服 务 器 


AE > aH 


头 名 称 不 是 必须 小 写 的 ， 并 且 重 复 也 没有 被 合并 。 





// Prints something like 
r-agent 
his 3 invalid becau there can be only one 
jser eni 
“curl/ 7.22.0", 
Host 
127 9000 


console.log(request.rawHeaders); 


message.trailers 


请 求 / 响 应 尾部 对 象 。 只 在 end 事件 中 存在 。 


message.rawTrailers 


接受 到 的 原始 请 求 /响应 头 尾部 键 值 对 。 只 在 end 事件 中 存在 。 


message.setTimeout(msecs, callback) 


e msecs Number 
e callback Function 


调用 message.connection.setTimeout(msecs, callback) ° 


返回 message ° 

message.method 

仅 对 从 http.Server 获得 的 请 求 有 效 。 

请 求 方法 是 字符 串 。 只 读 。 例 如 : 'GET' > 'DELETE' ° 
message.url 


仅 对 从 http.Server 获得 的 请 求 有 效 。 


请 求 的 URL 字 符 串 。 这 仅仅 只 包含 实际 HTTP 请 求 中 的 URL 。 如 果 请 求 是 : 


GET /status?name=ryan HTTP/1.1\r\n 
Accept: text/plain\r\n 
\r\n 


那么 request.url 将 是 : 


'/status?name=ryan' 


如 果 你 想 分 块 地 解释 URL。 你 可 以 调 
用 require('url').parse(request.url) 。 例 子 : 


iojs> require('url').parse('/status?name=ryan' ) 
{ href: '/status?name=ryan', 

search: '?name=ryan', 

query: 'name=ryan', 

pathname: '/status' } 


如 果 你 想 从 查询 字符 串 中 提取 参数 ， 你 可 以 使 
用 require('querystring').parse 函数 ， 或 者 给 require('url').parse 7 
法 的 第 二 个 参数 传递 true ， 例 子 : 


iojs> require('url').parse('/status?name=ryan', true) 
{ href: '/status?name=ryan', 

search: '?name=ryan', 

query: { name: 'ryan' }, 

pathname: '/status' } 


message.statusCode 
只 对 从 http.ClientRequest 到 来 的 响应 有 效 。 


3 位 整数 HTTP 状 态 码 。 如 404 © 


message.statusMessage 


只 对 从 http.ClientRequest 到 来 的 响应 有 效 。 


HTTP 响 应 状态 信息 。 如 OK 或 Internal Server Error 。 


message.socket 
与 此 连接 关联 的 net.Socket 对 象 。 


通过 HTTPS 的 支持 ， 使 用 request.socket.getPeerCertificate() 来 获取 客户 
端的 身份 细节 。 


HTTPS 


稳定 度 : 2 - 稳定 

HTTPS 是 建立 在 TLS/SSL 之 上 的 HTTP 协 议 。 在 node.js 中 ， 它 被 作为 单独 模块 
实现 。 

Class: https.Server 

这 个 类 是 tls.Server 的 子 类 ， 并 且 和 http.Server 触发 相同 的 事件 。 更 多 信息 
请 参阅 http.Server 。 

server.setTimeout(msecs, callback) 


参阅 http.Server#setTimeout() ° 


server.timeout 


参阅 http.Server#timeout ° 


https.createServer(options[, requestListener]) 


返回 一 个 新 的 HTTPS web 服 务 器 对 象 。 options 4 tls.createServer() 中 的 
类 似 。 requestListener 会 被 自动 添加 为 request 事件 的 监听 器 。 


例子 : 


// curl -k https://localhost :8000/ 
var https = require('https'); 
Var Ts = require(* is"): 


var options = { 
key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'), 
cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem' ) 


hg 


https.createServer (options, function (req, res) { 
res.writeHead(200); 
res.end("hello world\n"); 

}).listen(8000) ; 


x 


var https = require('https'); 
var fs = require('fs'); 


var options = { 
pfx: fs.readFileSync('server.pfx') 

J; 

https.createServer (options, function (req, res) { 
res.writeHead(200); 


res.end("hello world\n"); 
}).listen(8000); 


server.listen(port[, host][, backlog][, callback]) 
server.listen(path[, callback]) 


server.listen(handle[, callback]) 


详情 参阅 http.listen() ° 


server.close([callback]) 


详情 参阅 http.close() ° 


https.request(options, callback) 
向 一 个 安全 web 服 务 器 发 送 请 求 。 


options 可 以 是 一 个 对 象 或 一 个 字符 串 。 如 果 options 是 一 个 字符 串 ， 它 会 
动 被 url.parse() 解析 。 


所 有 的 http.request() 选项 都 是 可 用 的 。 
例子 : 
var https = require('https'); 


var options = { 
hostname: 'encrypted.google.com', 


port: 443, 
path: '/', 
method: 'GET' 


P 


var req = https.request(options, function(res) { 
console.log("statusCode: ", res.statusCode); 
console.log("headers: ", res.headers); 


res.on('data', function(d) { 
process.stdout.write(d); 


+); 
+); 
req.end(); 


req.on('error', function(e) { 
console.error(e); 


+); 


options 参数 有 以 下 选项 : 


e host: 一 个 将 要 向 其 发 送 请 求 的 服务 器 域名 或 |P 地 址 。 默 认为 localhost ° 
e hostname: host 的 别名 。 为 了 支持 url.parse() 的 


话 ， hostname 比 host 更 好 些 。 
e family: 解析 host 和 hostname 时 的 IP 地 址 协议 族 。 合 法 值 是 4 和 6 。 当 
没有 指定 时 ， 将 都 被 使 用 。 
o port: 远程 服务 器 端口 。 黑 认为 80 。 
e localAddress: 用 于 绑 定 网 络 连接 的 本 地 端口 。 
e socketPath: Unix 域 socket (使 用 host:port 或 socketPath ) ° 
e method: 指定 HTTP 请 求 方 法 的 字符 串 。 默 认为 GET 。 
e path: 请 求 路 径 。 默 认为 / 。 如 果 有 查询 字符 串 ， 则 需要 包含 。 例 
如 Vindex.html?page=12'。 请 求 路 径 包含 非法 字符 时 抛 出 异常 。 目 前 ， 只 否决 
空格 ， 不 过 在 未 来 可 能 改变 。 
e headers: 一 个 包含 请 求 头 的 对 象 。 
e auth: 用 于 计算 认证 头 的 基本 认证 ， 即 'user:password' ° 
e agent: 控制 agent 行为 。 当 使 用 一 个 代理 时 ， 请 求 将 默认 为 Connection: 
keep-alive 。 可 能 值 有 : 
o undefined (RU): 在 这 个 主机 和 端口 上 使 用 全 局 ‘agent。 
o Agent object: agent 中 显示 使 用 passed ° 
o false: 跳出 agent 的 连接 池 。 默 认 请 求 为 Connection: close ° 


以 下 来 自 tls.connect() 的 选项 也 可 以 被 指定 。 但 是 ， 一 个 globalAgent 会 默 
默 忽 略 这 些 。 


o pfx: 证 书 ，SSL 所 用 的 私 钥 和 CA 证书 。 默 认为 null e 

e key: SSL 所 用 的 私 钥 。 默 认为 null 。 

e passphrase: 私 钥 或 pfx 的 口令 字符 串 。 上 默认 为 null e 

e cert: 所 用 的 公共 X509 证 书 。 默 认为 null 。 

© Ca: 一 个 用 来 检查 远程 主机 的 权威 证 书 或 权威 证 书 数组 。 

e ciphers: 一 个 描述 要 使 用 或 排除 的 密码 的 字符 串 。 更 多 格式 信息 请 查 
询 http://www. openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FOR 
MAT ° 

e rejectUnauthorized: 如 果 设 置 为 true ， 服 务 器 证 书 会 使 用 所 给 的 CA 列表 验 
证 。 验 证 失败 时 ， 一 个 error 事件 会 被 触发 。 验 证 发 生 于 连接 层 ， 在 HTTP 请 
求 发 送 之 前 。 默 认为 true 。 

e secureProtocol: 所 用 的 SSL 方 法 ， 如 SSLv3_method 强制 使 用 SSL v3。 可 用 
的 值 取决 你 的 OpenSSL 安 装 和 SSL_METHODS 常量 。 


要 指定 这 些 选项 ， 使 用 一 个 自 定义 的 Agent 。 


例子 : 


var options = { 

hostname: 'encrypted.google.com', 

port: 443, 

path: 7 5 

method: 'GET', 

key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'), 

cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem' ) 
tr 


options.agent = new https.Agent(options); 


var req = https.request(options, function(res) { 


或 不 使 用 Agent ° 


例子 : 


var options = { 
hostname: 'encrypted.google.com', 
port: 443, 
atic” oy 
method: 'GET', 
key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'), 
cert: fs.readFileSync( 'test/fixtures/keys/agent2-cert.pem'), 
agent: false 


P 


var req = https.request(options, function(res) { 


https.get(options, callback) 
类 似 于 http.get() ， 但 是 使 用 HTTPS。 


options 可 以 是 一 个 对 象 或 一 个 字符 串 。 如 果 options 是 一 个 字符 串 ， 它 会 
动 被 url.parse() 解析 。 


例子 : 
var https = require('https'); 


https.get('https://encrypted.google.com/', function(res) { 
console.log("statusCode: ", res.statusCode); 
console.log("headers: ", res.headers); 


res.on('data', function(d) { 
process.stdout.write(d); 


+); 


}).on('error', function(e) { 
console.error(e); 


Pyg 


Class: https.Agent 


一 个 与 http.Agent 类 似 的 HTTPS Agent 对 象 。 更 多 信息 请 参 
阅 https.request() 。 


https.globalAgent 


所 有 HTTPS 客 户 端 请 求 的 全 局 https.Agent 实例 。 


Modules 
稳定 度 :3 -锁定 
node.js 又 一 个 简单 的 模块 加 载 系统 。 在 node.js 中 ， 文 件 和 模块 是 一 一 对 应 
的 。 以 下 例子 中 ， foo.js 加 载 的 同 目录 下 的 circle.js 。 
foo.js WAX: 
var circle = require('./circle.js'); 


console.log( 'The area of a circle of radius 4 is ' 
+ circle.area(4)); 


circle.js NAB: 
var PI = Math.PI; 


exports.area = function (r) { 
Return PL ar * 1; 


ia 


exports.circumference = function (r) { 
return 2.7 Pl * rp: 


Po 


circle.js 模块 暴露 了 area() 函数 和 circumference() 函数 。 想 要 为 你 的 模 
块 添加 函数 或 对 象 ， 你 可 以 将 它们 添加 至 特殊 的 exports 对 象 的 属性 上 。 


模块 的 本 地 变量 是 私有 的 ， 好 似 模 块 被 包 衰 在 一 个 函数 中 。 在 这 个 例子 中 交 
量 PI 是 circle.js 私有 的 。 


如 果 想 要 你 的 模块 暴露 一 个 函数 (例如 一 个 构造 函数 ) ， 或 者 想 要 一 次 赋值 就 暴露 
一 个 完整 的 对 象 ， 而 不 是 一 次 绑 定 一 个 属性 ， 那 就 将 之 赋值 
给 module.exports 而 不 是 exports 。 


以 下 ， bar .js 使 用 了 暴露 了 一 个 构造 函数 的 square 模块 : 


var square = require('./square.js'); 
var mySquare = square(2); 
console.log('The area of my square is ' + mySquare.area()); 


square 模块 内 部 : 


// assigning to exports will not modify module, must use module. 
exports 
module.exports = function(width) { 
return { 
area: function() { 
return width * width; 


J; 


模块 系统 在 require("module") 中 被 实现 。 


5 3 
循环 依赖 
当 存 在 循环 的 require() 调用 。 一 个 模块 可 能 在 返回 时 ， 被 没有 被 执行 完毕 。 
考虑 一 下 情况 : 

a.js 

console.log('a starting'); 

exports.done = false; 

var b = require('./b.js'); 

console.log('in a, b.done = %j', b.done); 


exports.done = true; 
console.log('a done'); 


b.js 


console.log('b starting'); 

exports.done = false; 

var a = require('./a.js'); 
console.log('in b, a.done = %j', a.done); 
exports.done = true; 

console.log('b done'); 


main.js 


console.log('main starting'); 
var a = require('./a.js'); 
var b = require('./b.js'); 


console.log('in main, a.done=%j, b.done=%j', a.done, b.done); 


4 main.js 加 载 a.js ， 而 后 a.js 会 去 加 载 b.js 。 与 此 同时 ， 


b.js 尝试 


去 加 载 ajs 。 为 了 避免 一 个 无 限 循 环 ， ajs 会 返回 一 个 未 完成 的 副本 
给 b.js 模块 。 b,js 会 接着 完成 加 载 ， 然 后 它 所 暴露 的 值 再 被 提供 给 ajs 模 


块 。 


这 样 main.js 就 完成 了 它们 的 加 载 。 因 此 程序 的 输出 是 : 


$ iojs main.js 

main starting 

a starting 

b starting 

in b, a.done = false 
b done 


in a, b.done = true 
a done 
in main, a.done=true, b.done=true 


如 果 在 你 的 程序 里 有 循环 依赖 ， 请 确保 它们 按 你 的 计划 工作 。 


核心 模块 


node.js 中 有 一 些 模块 是 被 编译 成 二 进 制 的 。 这 些 模 块 会 在 本 文档 的 


细 付 论 。 


其 他 地 方 详 


核心 模块 被 定义 在 node.js 源码 的 lib/ ARF ° 


当 被 require() 时 ， 核 心 模块 总 是 被 优先 加 载 的 。 例 如 require('http') 总 是 
会 返回 内 建 的 HTTP 模 块 ， 其 至 是 有 一 个 同名 文件 时 。 


文件 模块 


如 果 准 确 的 文件 名 没有 被 发 现 ， 那 么 node.js 将 会 依次 添 
加 ,js ， .json 或 ,node 后 级 名 ， 然 后 试图 去 加 载 。 


.js 文件 被 解释 为 JavaScript 文本 文件 ， .json 被 解释 为 JSON 文本 文 
件 ， .node 文件 被 解释 为 编译 好 的 插件 模块 ， 然 后 被 dlopen 加 载 。 


前 级 是 '/' 则 是 文件 的 绝对 路 径 。 例 如 require('/home/marco/foo.js') 将 会 


加 载 /home/marco/foo.js ° 


前 级 是 ',/' 则 是 调用 require() 的 文件 的 相对 路 径 。 也 就 是 

说 ， circle.js 必须 与 foo.js 在 同一 目录 下 ， 这 样 require('./circle') 4 
能 找到 它 。 

如 果 没 有 '/' ，'./' 或 ',,/'， 前 级 ， 模 块 要 么 是 一 个 核心 模块 ， 或 是 需要 

从 node_modules 目录 中 被 加 载 。 


如 果 指 定 的 路 径 不 存在 ， require() 将 会 抛 出 一 个 code 属性 


日 


是 'MODULE_NOT_FOUND' 的 错误 。 


从 node_modules 目 录 中 加 载 

如 果 传 递 给 require() 的 模块 标识 符 不 是 一 个 本 地 模块 ， 也 没有 

以 '/' ，',./' 或 ',/' 开始 。 那 么 node.js 将 会 从 当前 目录 的 父 目 录 开 始 ， 
添加 /node_modules ， 试 图 从 这 个 路 径 来 加 载 模块 。 

如 果 还 是 没有 找到 模块 ， 那 么 它 会 再 移 至 此 目录 的 父 上 目录， 如 此 往复 ， 直 至 到 达 文 
件 系统 的 根 目 录 。 


例如 ， 如 果 一 个 位 于 '/home/ry/projects/foo.js' 的 文件 调用 
J require('bar.js') > Z2 node.js 将 会 按照 以 下 的 路 径 顺 序 来 查找 : 


/home/ry/projects/node_modules/bar.js 
/home/ry/node_modules/bar.js 
/home/node_modules/bar.js 
/node_modules/bar.js 


这 要 求 程序 本 地 化 (localize) 自己 的 依赖 ， 防 止 它们 崩溃 。 


你 也 可 以 在 模块 名 中 加 入 一 个 路 径 后 级 ， 来 引用 这 个 模块 中 特定 的 一 个 文件 或 子 模 
块 。 例 如 ， require('example-module/path/to/file') 将 会 从 example- 
module 的 位 置 解析 相对 路 径 path/to/file 。 路 径 后 组 遵循 相同 的 模块 解析 语 
Na o 


作为 模块 的 目录 


在 一 个 单独 目录 下 组 织 程序 和 库 ， 然 后 提供 一 个 单独 的 入 口 ， 是 非常 便捷 的 。 有 三 
种 方法 ， 可 以 将 目录 作为 require() 的 参数 ， 来 加 载 模块 。 


第 一 种 方法 是 ， 在 模块 的 根 目录 下 创建 一 个 package.json 文件 ， 其 中 指定 


了 main 模块 。 一 个 示例 package.json 文件 : 


{ "name" : "some-library", 
"main" : "./lib/some-library.js" } 


如 果 这 个 文件 位 于 ./some-library >? ARA require('./some-library') 将 会 
试图 去 加 载 ./some-library/lib/some-library.js ° 


这 就 是 node.js Mies TM package.json 文件 的 程度 。 


如 果 目 录 中 没有 package.json 文件 ， 那 么 node.js 将 会 视图 去 加 载 当 前 目录 中 
的 index.js 或 index.node 。 例 如 ， 如 果 在 上 面 的 例子 中 没 
有 package.json ， 那 么 require('./some-library') 将 会 试图 加 载 : 


./some-library/index.js 
./some-library/index.node 


BAG 


模块 在 第 一 次 被 加 载 后 ， 会 被 缓存 。 这 意味 着 ， 如 果 都 解析 到 了 相同 的 文件 ， 每 一 
次 调用 require('foo') 都 将 会 返回 同一 个 对 象 。 


多 次 调用 require('foo') 可 能 不 会 造成 模块 代码 被 执行 多 次 。 这 是 一 个 重要 的 
特性 。 有 了 它 ，* 部 分 完成 ”的 对 象 也 可 以 被 返回 ， 这 样 ， 传 递 依 赖 也 能 被 加 载 ， 即 
使 它们 可 能 会 造成 循环 依赖 。 


如 果 你 想 要 一 个 模块 被 多 次 执行 ， 那 么 就 暴露 一 个 函数 ， 然 后 执行 这 个 函数 。 


模块 缓存 警告 


模块 的 缓存 依赖 于 它们 被 解析 后 的 文件 名 。 所 以 调用 模块 的 位 置 不 同 ， 可 以 会 解析 
出 不 同 的 文件 名 (比如 需要 从 node modules 目 录 中 加 载 ) 。 所 以 不 能 保 

证 require('foo') 总 是 会 返回 相同 的 对 象 ， 因 为 它们 可 能 被 解析 为 了 不 同 的 文 
件 。 


module 对 象 
e {Object} 


每 一 个 模块 中 ， 变 量 module 是 一 个 代表 了 当前 模块 的 引用 。 为 了 方 
便 ， module.exports 也 可 以 通过 模块 作用 域 中 的 exports 取得 。 module 对 
象 实际 上 不 是 全 局 的 ， 而 是 每 个 模块 本 地 的 。 


module.exports 


e Object 


module.exports 对 象 是 由 模块 系统 创建 的 。 有 时 这 是 难以 接受 的 ; 许多 人 和 希望 
它们 的 模块 是 一 些 类 的 实例 。 如 果 需 要 这 样 ， 那 么 就 将 想 要 暴露 的 对 象 赋值 

给 module.exports 。 注 意 ， 将 想 要 暴露 的 对 象 传递 给 exports ， 将 仅仅 只 会 重 
MAE (rebind) 本 地 变量 exports ， 所 以 不 要 这 么 做 。 


例如 假设 我 们 正在 写 一 个 叫做 a.js 的 模块 : 


var EventEmitter = require('events').EventEmitter; 
module.exports = new EventEmitter(); 


// Do some work, and after some time emit 

// the 'ready' event from the module itself. 

setTimeout(function() { 
module.exports.emit('ready'); 

}, 1000); 


那么 在 另 一 个 文件 中 我 们 可 以 : 


var a = require('./a'); 
a.on('ready', function() { 
console.log('module a is ready'); 


}); 
主要 ， 对 module.exports 的 赋值 必须 立刻 完成 。 它 不 能 在 任何 的 回调 函数 中 完 
成 。 以 下 例子 将 不 能 正常 工作 : 


XS 


setTimeout(function() { 
module.exports = { a: "hello" }; 
}, ©); 
y.js 
var x = require('./x'); 
console.log(x.a); 
exports 快 捷 方 式 


exports 变量 是 一 个 module.exports 的 引用 。 如 果 你 将 一 个 新 的 值 赋 予 它 ， 那 
么 它 将 不 再 指向 先前 的 那个 值 。 


为 了 说 明 这 个 行为 ， 将 require() 的 实现 假设 为 这 样 : 


function require(...) 4 
/0 
function (module, exports) { 
// Your module code here 
exports = some_func; // re-assigns exports, exports 1 
s no longer 
// a shortcut, and nothing is ex 
ported. 
module.exports = some_func; // makes your module export 0 
} (module, module.exports); 
return module; 


一 个 指导 方针 是 ， 如 果 你 再 不 清楚 exports 和 module.exports ZANKA > FH 
只 使 用 module.exports ° 
module.require(id) 


e id String 
e Return: 被 解析 的 模块 的 module.exports 


module.require 方法 提供 了 一 种 像 require() 一 样 ， 从 源 模块 中 加 载 模块 的 方 
法 。 


注意 ， 为 了 这 么 做 ， 你 必须 取得 module 对 象 的 引用 。 因 为 require() & 

回 module.exports ， 并 且 module 对 象 是 一 个 典型 的 只 在 特定 的 模块 作用 域 中 
有 效 的 变量 ， 如 果 要 使 用 它 ， 必 须 被 明确 地 导出 。 

module.id 


e String 
模块 的 识别 符 。 通 常 是 被 完全 解析 的 文件 名 。 
module.filename 


e String 


模块 完全 解析 后 的 文件 名 。 


module.loaded 


e Boolean 
模块 是 否 加 载 完 成 ， 或 者 是 正在 加 载 的 过 程 中 。 
module.parent 
e Module Object 
引用 这 个 模块 的 模块 。 
module.children 
e Array 
这 个 模块 所 引入 的 模块 。 
总 体 来 说 


为 了 获得 require() 被 调用 时 将 要 被 加 载 的 准确 文件 名 ， 使 


用 require.resolve() 函数 。 


综 上 所 述 ， 以 下 是 一 个 require.resolve 所 做 的 事 的 高 级 算法 伪 代 码 : 


require(X) from module at path Y 
1. If X is a core module, 
a. return the core module 
b. STOP 
2. If X begins with ”or '/" Or '../' 
a. LOAD_AS_FILE(Y + X) 
b. LOAD_AS_DIRECTORY(Y + X) 
3. LOAD_NODE_MODULES(X, dirname(Y)) 
4. THROW "not found" 


LOAD_AS_FILE(X) 
1. If X is a file, load X as JavaScript text. STOP 
2. If X.js is a file, load X.js as JavaScript text. 


3. If X.json is a file, parse X.json to a JavaScript Object. 


OP 
4. If X.node is a file, load X.node as binary addon. 


ST 


LOAD_AS_ DIRECTORY (X) 
1. If X/package.json is a file, 
a. Parse X/package.json, and look for "main" field. 
b. let M = X + (json main field) 
c. LOAD AS FILE(M) 
2. If X/index.js is a file, load X/index.js as JavaScript text. 
STOP 
3. If X/index.json is a file, parse X/index.json to a JavaScript 
object. STOP 
4. If X/index.node is a file, load X/index.node as binary addon. 
STOP 


LOAD_NODE_MODULES(X, START) 
1. let DIRS=NODE_MODULES_PATHS(START ) 
2. for each DIR in DIRS: 

a. LOAD_AS_FILE(DIR/X) 

b. LOAD AS DIRECTORY(DIR/X) 


NODE_MODULES_PATHS(START ) 
1. let PARTS = path split(START) 
2. let I = count of PARTS - 1 
3. let DIRS = [] 
4. while I >= 0, 
a. if PARTS[I] = "node_modules" CONTINUE 
c. DIR = path join(PARTS[O .. I] + "node_modules") 
b. DIRS = DIRS + DIR 
c. let I=I -1 
5. return DIRS 


从 全 局 文件 夹 加 载 


如 果 NODE_PATH 环境 变量 被 设置 为 了 一 个 以 冒号 分 割 的 绝对 路 径 列 表 ， 那 么 在 找 
不 到 模块 时 ， node.js 将 会 从 这 些 路 径 中 寻找 模块 (注意 : 在 Windows 
中 ， NODE_PATH 是 以 分 号 间隔 的 ) 。 


NODE_PATH 最 初 被 创建 ， 是 用 来 支持 在 当前 的 模块 解析 算法 被 冻结 (frozen) 
前 ， 从 不 同 的 路 径 加 载 模块 的 。 


NODE_PATH 仍然 被 支持 ， 但 是 ， 如 今 node.js 生态 圈 已 经 有 了 放置 依赖 模块 的 
公约 ， 它 已 经 不 那么 必要 的 。 有 时 ， 当 人 们 没有 意识 到 NODEPATH 有 被 设置 时 ， 
依赖 于 NODE_PATH 的 部 署 可 能 会 产生 出 人 意料 的 表现 。 有 了 时， 一 个 模块 的 依赖 改 
变 了 ， 造 成 了 通过 NODE_PATH ， 加 载 了 不 同 版 本 的 模块 。 


另外 ， node.js 将 会 查找 以 下 路 径 : 


e 1: $HOME/.node_modules 
e 2: $HOME/.node_libraries 
e 3: $PREFIX/lib/node 


$HOME 是 用 户 的 家 目录 ， $PREFIX 是 node.js 中 配置 的 node_prefix ° 
由 于 一 些 历史 原因 ， 高 度 推荐 你 将 依赖 放 入 node_modules 目录 。 它 会 被 加 载 的 
更 快 ， 且 可 靠 性 更 好 。 
访问 主 模块 
当 一 个 文件 直接 由 node.js 执行 ， require.main 将 被 设置 为 这 个 模块 。 这 意味 


着 你 可 以 判断 一 个 文件 是 否 是 直接 被 运行 的 。 


require.main === module 


对 于 一 个 文件 foo.js ， 如 果 通 过 iojs foo.js 运行 ， 以 上 将 会 返回 true 。 如 
果 通 过 require('./foo') ， 将 会 返回 false 。 


因为 module 提供 了 一 个 filename 属性 (通常 等 于 _ filename ) ， 所 以 当前 
应 用 的 入 口 点 可 以 通过 检查 require.main.filename 来 获取 。 
附录 : 包 管 理 小 贴 士 


node.js 的 require() 部 数 的 语义 被 设计 得 足够 通用 ， 来 支持 各 种 目录 结构 。 
包 管 理 程序 诸如 dpkg > rpm 和 npm 将 可 以 通过 不 修改 node.js 模块 ， 来 构建 
本 地 包 


以 下 我 们 给 建议 的 可 行 的 目录 结构 : 


假设 /usr/lib/node/<some-package>/<some-version> 中 有 指定 版 本 包 的 内 


容 。 


包 可 以 依赖 于 其 他 包 。 为 了 安装 foo 包 ， 你 可 能 需要 安装 特定 版 本 
的 bar 包 。 bar 包 可 能 有 它 自己 的 依赖 ， 在 一 些 情况 下 ， 它 们 的 依赖 可 以 会 冲突 
或 者 产生 循环 。 


由 于 node.js 会 查找 任何 它 加 载 的 包 得 丨 实 路 径 (也 就 是 说 ， 解 
析 symlinks ) ， 解 析 以 下 结构 的 方案 非常 简单 : 


e /usr/lib/node/foo/1.2.3/- foo 包 的 内 容 ，1.2.3 版 本 。 

e /usr/lib/node/bar/4.3.2/- foo 包 所 依赖 的 bar 包 的 内 容 。 

e /usr/lib/node/foo/1.2.3/node_modules/bar - 指 
 /usr/lib/node/bar/4.3.2/ 的 符号 链接 。 

e /usr/lib/node/bar/4.3.2/node_modules/* - 指向 bar 包 所 依赖 的 包 的 符号 链 
接 。 


因此 ， 即 使 有 循环 依赖 ， 或 者 依赖 冲突 ， 每 个 模块 都 能 够 获取 它们 使 用 的 特定 版 本 
的 依赖 。 


当 foo 包 中 的 代码 执行 require('bar') ， 将 会 获得 符号 链 

接 /usr/lib/node/foo/1.2.3/node_modules/bar 指向 的 版 本 。 接 着 ， bar & 
种 的 代码 执行 require('quux') ， 它 将 会 获得 符号 链 

接 /usr/lib/node/bar/4.3.2/node_modules/quux 指向 的 版 本 。 


此 外 ， 为 了 优化 模块 查找 的 过 程 ， 我 们 将 模块 放 

在 /usr/lib/node_modules/<name>/<version> 而 不 是 直接 放 

在 /usr/lib/node 中 。 然 后 在 找 不 到 依赖 时 ， node.js 就 不 会 一 直 去 查 
找 /usr/node_modules 或 /node_modules 目录 了 。 


为 了 让 模块 在 node.js 的 REPL 中 可 用 ， 可 能 需 

将 /usr/lib/node_modules 目录 加 入 到 $NODE_PATH 环境 变量 。 因 为 使 

用 node_modules 目录 的 模块 查找 都 是 使 用 相对 路 径 ， 且 基于 调用 require() 的 
文件 的 申 实 路 径 ， 因 此 包 本 身 可 以 在 任何 位 置 。 


net 


稳定 度 : 2 -稳定 

net 模块 为 你 提供 了 异步 的 网 络 调用 的 包装 。 它 同时 包含 了 创建 服务 器 和 客户 端 
的 函数 。 你 可 以 通过 require('net') 来 引入 这 个 模块 。 
net.createServer([options][, connectionListener]) 


创建 一 个 新 的 TCP 服 务 器 。 connectionListener 参数 会 被 自动 绑 定 
A connection 事件 的 监听 器 。 


options 是 一 个 包含 下 列 默 认 值 的 对 象 : 


{ 
allowHalfOpen: false, 


pauseOnConnect: false 


如 果 allowHalfOpen 是 true ， 那 么 当 另 一 端的 socket 发 送 一 个 FIN AX 
时 socket 并 不 会 自动 发 送 FIN 报 文 。 socket 变 得 不 可 读 ， 但 是 可 写 。 你 需要 
明确 地 调用 end() 方法 。 详 见 end 事件 。 


如 果 pauseOnConnect 是 true， 那 么 socket 在 每 一 次 被 连接 时 会 暂停 ， 并 且 不 
会 读 取 数据 。 这 允许 在 进程 间 被 传递 的 连接 不 读 取 任何 数据 。 如 果 要 让 一 个 被 暂停 
的 socket 开始 读 取 数据 ， 调 用 resume() 方法 。 


以 下 是 一 个 应 答 服务 器 的 例子 ， 监 听 8124 端 口 : 


var net = require('net'); 
var server = net.createServer(function(c) { //'connection' liste 
ner 
console.log('client connected'); 
c.on('end', function() { 
console.log('client disconnected'); 


+); 
c.write('hello\r\n'); 
c.pipe(c); 
}); 
server.listen(8124, function() { //'listening' listener 
console.log('server bound'); 


}); 


使 用 telnet 测试 : 


telnet localhost 8124 


想 要 监听 socket’ */tmp/echo.sock ， 只 需 改 变 倒数 第 三 行 : 


server.listen('/tmp/echo.sock', function() { //'listening' liste 
ner 


使 用 nc 连接 一 个 UNIX domain sockethR 4 & : 


nc -U /tmp/echo.sock 


net.connect(options[, connectionListener]) 


net.createConnection(options[, connectionListener]) 


工厂 函数 ， 返 回 一 个 新 的 net.Socket 实例 ， 并 且 自 动 使 用 提供 的 options 进行 
连接 。 


options 会 被 同时 传递 给 net.Socket 构造 函数 和 socket.connect 方法 。 


参数 connectListener 将 会 被 立即 添加 为 connect 事件 的 监听 器 。 


下 面 是 一 个 上 文 应 答 服 务 器 的 客户 端的 例子 : 


var net = require('net'); 
var client = net.connect({port: 8124}, 
function() { //'connect' listener 
console.log('connected to server!'); 
client.write('world!\r\n'); 


}); 

client.on('data', function(data) { 
console.log(data.toString()); 
client.end(); 


+); 
client.on('end', function() { 
console.log('disconnected from server'); 


+); 


要 连接 socket’ */tmp/echo.sock 只 需要 改变 第 二 行为 : 


var client = net.connect({path: '/tmp/echo.sock'}); 


net.connect(port[, host][, connectListener]) 


net.createConnection(port[, host][, connectListener]) 


工厂 函数 ， 返 回 一 个 新 的 net.Socket 实例 ， 并 且 自 动 使 用 指定 的 端口 (port) 和 主 
机 (host) 进 行 连接 。 


如 果 host RAR?’ RUA localhost ° 


参数 connectListener 将 会 被 立即 添加 为 connect 事件 的 监听 器 。 
net.connect(path[, connectListenen]) 


net.createConnection(path[, connectListener]) 


工厂 函数 ， 返 回 一 个 新 的 unix net ,Socket 实例 ， 并 且 自 动 使 用 提供 的 路 径 (path) 
进行 连接 。 


参数 connectListener 将 会 被 立即 添加 为 connect 事件 的 监听 器 。 


Class: net.Server 


这 个 类 用 于 创建 一 个 TCP 或 本 地 服务 器 。 


server.listen(port[, hostname][, backlog][, callback]) 


开始 从 指定 端口 和 主机 名 接收 连接 。 如 果 省 略 主机 名 ， 那 么 如 果 IPv6 可 用 ， 服 务 器 
会 接受 从 任何 IPv6 地 址 (::) 来 的 链接 ， 否 则 为 任何 IPv4 地 址 (0.0.0.0) 。 如 果 端 
口 为 0 那么 将 会 为 其 设置 一 个 随机 端口 。 


REE backlog 是 连接 等 待 队列 的 最 大 长 度 。 实 际 长 度 由 你 的 操作 系统 
的 sysctl 设置 决定 (如 |inux 中 的 tcp_max_syn_backlog 和 somaxconn ) ° È 
个 参数 的 默认 值 是 511 (不 是 512) 。 


这 个 函数 式 异 步 的 。 当 服务 器 绑 定 了 指定 端口 后 ， listening 事件 将 会 被 触发 。 
最 后 一 个 参数 callback 将 会 被 添加 为 listening 事件 的 监听 器 。 


有 些 用 户 可 能 遇 到 的 情况 是 收 到 EADDRINUSE 错误 。 这 意味 着 另 一 个 服务 器 已 经 
使 用 了 该 端口 。 一 个 解决 的 办 法 是 等 待 一 段 时 间 后 重 试 。 


server.on('error', function (e) { 
if (e.code == 'EADDRINUSE') { 
console.log('Address in use, retrying...'); 
setTimeout(function () { 
server .close(); 
server.listen(PORT, HOST); 
7 LOO); 
} 
}); 


(注意 ， node.js 中 所 有 的 socket 都 已 经 设置 了 SO_REUSEADDR ) 


server.listen(path[, callback]) 


e path String 
e callback Function 


启动 一 个 本 地 socket 服务 器 ， 监 听 指 定 路 径 ( path ) 上 的 连接 。 


这 个 函数 式 异 步 的 。 当 服务 器 监听 了 指定 路 径 后 ， listening 事件 将 会 被 触发 。 
最 后 一 个 参数 callback 将 会 被 添加 为 listening 事件 的 监听 器 。 

在 UNIX 中 ， local domain 经 常 被 称 作 UNIX domain 。 path 是 一 个 文件 系统 
路 


径 名 。 它 在 被 创建 时 会 受 相同 文件 名 约定 (same naming conventions) 的 限制 并 且 
进行 权限 检查 (permissions checks)。 它 在 文件 系统 中 可 见 ， 并 且 在 被 删除 前 持续 存 


在 Windows 中 ， local doamin 使 用 一 个 命名 管道 (named pipe) 实 

现 。 path 必须 指向 \\?\pipe\ 2 \\.\pipe\. 中 的 一 个 条 目 ， 但 是 后 者 可 能 
会 做 一 些 命名 管道 的 处 理 ， 如 处 理 .， 序列 。 除 去 表现 ， 命 名 管道 空间 是 平坦 的 
(flat) 。 管 道 不 会 持续 存在 ， 它 们 将 在 最 后 一 个 它们 的 引用 关闭 后 被 删除 。 不 要 总 
记 ， 由 于 JavaScript 的 字符 串 转 义 ， 你 必须 在 指定 path 时 使 用 双 反 斜 杠 : 


net.createServer().listen( 
path. join('\\\\?\\pipe', process.cwd(), 'myctl')) 


server.listen(handle[, callback]) 


e handle Object 
e callback Function 


handle 对 得 可 以 被 设置 为 一 个 服务 器 或 一 个 socket (或 者 任意 以 下 划 线 开头 
的 成 员 handle ) ， 或 者 一 个 {fd: <n>} 对 象 。 


这 将 使 得 服务 器 使 用 指定 名 柄 接受 连接 ， 但 它 假设 文件 描述 符 或 句柄 已 经 被 绑 定 至 
间 定 的 端口 或 域名 socket 。 


在 Windows 下 不 支持 监听 一 个 文件 描述 符 。 
DN BEAR HK o SIRF SCRAP LE > listening 事件 将 会 被 触发 。 最 后 一 
个 参数 callback 将 会 被 添加 为 listening 事件 的 监听 器 。 
server.listen(options[, callback]) 

e options Object 


o port Number 可 选 
o host String 可 选 
o backlog Number 可 选 


o path String 可 选 
o exclusive Boolean 可 选 
e callback Function 可 选 


port ， host 和 backlog 属性 ， 以 及 可 选 的 callback HA? 
与 server.listen(port, [host], [backlog], [callback]) 中 表现 一 
Keo path 可 以 被 指定 为 一 个 UNIX socket 。 


如 果 exclusive 是 false (RU) ， 那 么 工作 集群 (cluster workers) 将 会 使 用 
相同 的 底层 句柄 ， 处 理 的 连接 的 职责 将 会 被 它们 共享 。 如 

Æ exclusive Æ true ， 那 么 句 杨 是 不 被 共享 的 ， 企 图 共享 将 得 到 一 个 报错 的 结 
果 。 下 面 是 一 个 监听 独 有 端口 的 例子 : 


server.listen({ 
host: 'localhost', 


port: 80, 
exclusive: true 
+); 


server.close([callback]) 


使 服务 器 停止 接收 新 的 连接 并 且 保 持 已 存在 的 连接 。 这 个 函数 式 异 步 的 ， 当 所 有 的 
连接 都 结束 时 服务 器 会 最 终 关闭 ， 并 处 罚 一 个 close 事件 。 可 选 的 ， 你 可 以 传递 
一 个 回调 函数 来 监听 close 事件 。 如 果 传递 了 ， 那 么 它 的 唯一 的 第 一 个 参数 将 表 
示 任 何 可 能 潜在 发 生 的 错误 。 


server.address() 


返回 服务 器 绑 定 的 地 址 ， 协 议 族 名 和 端口 通过 操作 系统 报告 。 对 查找 操作 系统 分 配 
的 地 址 哪个 端口 被 分 配 非常 有 有 用。 返回 一 个 有 三 个 属性 的 对 象 。 如 { port: 
12346, family: 'IPv4', address: '127.0.0.1' } ° 


例子 : 


var server = net.createServer(function (socket) { 
socket.end("goodbye\n"); 
}); 


// grab a random port. 
server.listen(function() { 
address = server.address(); 
console.log("opened server on %j", address); 


}); 


在 listening 事件 触发 前 ， 不 要 调用 server.address() 方法 。 


server.unref() 


调用 一 个 server 48% unref 方法 将 允许 如 果 它 是 事件 系统 中 唯一 活跃 的 服务 
器 ， 程 序 将 会 退出 。 如 果 服 务 器 已 经 被 调用 过 这 个 方法 ， 那 么 再 次 调用 这 个 方法 将 
不 会 有 任何 效果 。 


返回 server He 


server.ref() 


与 unref 相反 ， 在 一 个 已 经 被 调用 unref 方法 的 server 中 调用 ref Aik > Ap 
么 如 果 它 是 唯一 活跃 的 服务 器 时 ， 程 序 将 不 会 退出 (RU) 。 如 果 服 务 器 已 经 被 调 
用 过 这 个 方法 ， 那 么 再 次 调用 这 个 方法 将 不 会 有 任何 效果 。 


返回 server 对 象 。 

server.maxConnections 

设置 了 这 个 属性 后 ， 服 务 器 的 连接 数 达 到 时 将 会 开始 拒绝 连接 。 

一 旦 socket 被 使 用 child_process.fork() 传递 给 了 子 进 程 ， 这 个 属性 就 不 被 
推荐 去 设置 。 

server.connections 


这 个 函数 已 经 被 弃 用 。 请 使 用 server.getConnections() #7 ° 


服务 器 的 当前 连接 数 。 


当 使 用 child_process.fork() 传递 一 个 socket 给 了 予 进 程 时 ， 这 个 属性 将 变 


成 null 。 想 要 得 到 正确 的 结果 请 使 用 server.getConnections ° 


server.getConnections(callback) 


异步 地 去 获取 服务 器 的 当前 连接 数 ， 在 socket 被 传递 给 子 进程 时 仍然 可 用 。 


回调 函数 的 两 个 参数 是 err 和 count ° 


net .Server 是 一 个 具有 以 下 事件 
的 EventEmitter 


Event: ‘listening’ 


当 调 用 server.listen Æ > RAS CRA CH ° 


Event: ‘connection’ 
e Socket object 连接 对 象 


当 新 的 连接 产生 时 触发 。 socket 是 一 个 net.Socket 实例 。 


Event: ‘close’ 


当 服 务 器 关闭 时 触发 。 注 意 如 果 服 务 器 中 仍 有 连接 存在 ， 那 么 这 个 事件 会 直 


的 连接 都 关闭 后 才 触 发 。 


Event: ‘error’ 


e Error Object 


当 发 生 错 误 时 触发 。 close 事件 将 会 在 它 之 后 立即 触发 。 参 


阅 server.listen ° 


Class: net.Socket 


到 所 有 


这 个 对 象 是 一 个 TCP 或 本 地 socket 的 抽象 。 net.Socket 实例 实现 了 双 工 流 
(duplex Stream) 接口 。 它 可 以 被 使 用 者 创建 ， 并 且 被 作为 客户 端 ( 配 
合 connect() ) 使 用 。 或 者 也 可 以 被 node.js 创建， 并且 通过 服务 器 
的 connection 事件 传递 给 使 用 者 。 
new net.Socket([options]) 
创建 一 个 新 的 socket tHe 
options 是 一 个 有 以 下 默认 值 的 对 象 : 
{ fd: null 
allowHalfOpen: false, 


readable: false, 
writable: false 


fd 允许 你 使 用 一 个 指定 的 已 存在 的 socket 文件 描述 符 。 设 置 readable 和 /或 
writable 为 true 将 允许 从 这 个 socket 中 读 和 /或 写 (注意 ， 仅 在 传递 
了 passed 时 可 用 ) 。 关 于 allowHalfopen ， 参 
阅 createServer() 和 end 事件 。 
socket.connect(options[, connectListener]) 
从 给 定 的 socket 打开 一 个 连接 。 
对 于 TCP socket ， options 参数 需 是 一 个 包含 以 下 属性 的 对 象 : 
e port: 客户 端 需要 连接 的 端口 〈 必 选 ) 。 
e host: 客户 端 需 要 连接 的 主机 (默认 : localhost) 
e localAddress: 将 要 绑 定 的 本 地 接口 ， 为 了 网 络 连接 。 
e localPort: 将 要 绑 定 的 本 地 端口 ， 为 了 网 络 连 接 。 
e family : IP 协 议 族 版 本 ， 默 认为 4 © 
e lookup: 自 定 义 查找 函数 。 默 认为 dns.lookup ° 


对 于 本 地 domain socket > options 参数 需 是 一 个 包含 以 下 属性 的 对 象 : 


e path: 客户 端 需要 连接 的 路 径 (sb) 。 


通常 这 个 方法 是 不 需要 的 ， 因 为 通过 net.createConnection 打开 socket ° R 
有 在 你 自 定 义 了 socket 时 才 使 用 它 


o 


这 个 函数 式 异 步 的 ， 当 connect 事件 触发 时 ， 这 个 socket 就 被 建立 了 。 如 果 在 
连接 的 过 程 有 有 问题， 那么 connect 事件 将 不 会 触发 ， error 将 会 带 着 这 个 异常 
触发 。 


connectListener 参数 会 被 自动 添加 为 connect 事件 的 监听 器 。 
socket.connect(port[, host][, connectListener]) 


socket.connect(path[, connectListener]) 


参阅 socket.connect(options[, connectListener]) ° 


socket.bufferSize 


net.Socket 的 属性 ， 用 于 socket.write() 。 它 可 以 帮助 用 户 获 取 更 快 的 运行 
速度 。 计 算 机 不 能 一 直 保 持 大 量 数据 被 写 入 socket 的 状态 ， 网 络 连接 可 以 很 
Me node.js 在 内 部 会 排队 等 候 数据 被 写 入 socekt 并 确保 传输 连接 上 的 数据 完 
好 。 (内 部 实现 为 : 轮 询 socekt 的 文件 描述 符 等 待 它 为 可 写 )。 


内 部 缓存 的 可 能 结果 是 内 存 使 用 会 增长 。 这 个 属性 展示 了 缓存 中 还 有 多 少 待 写 入 的 
字符 (字符 的 数目 约 等 于 要 被 写 入 的 字 节 数 ， 但 是 缓冲 区 可 能 包含 字符 事 ， 而 字符 
串 是 惰性 编码 的 ， 所 以 确切 的 字 节 数 是 未 知 的 ) 。 


遇 到 数值 很 大 或 增长 很 快 的 bufferSize 时 ， 应 当 尝 试 使 
用 pause() 和 resume() 来 控制 。 


socket.setEncoding([encoding]) 


设置 socket 的 编码 作为 一 个 可 读 流 。 详 情 参 阅 stream.setEncoding() ° 


socket.write(data[, encoding][, callback]) 


在 套 接 字 上 发 送 数据 。 第 二 个 参数 指定 了 字符 串 的 编码 ， 黑 认为 UTF8 。 


如 果 所 有 数据 成 功 被 刷新 至 了 内 核 缓 冲 区 ， 则 返回 true 。 如 果 所 有 或 部 分 数据 仍 
然 在 用 户 内 存 中 排队 ， 则 返回 false 。 drain 事件 将 会 被 触发 当 buffer 再 次 
为 空 时 。 


当 数 据 最 终 被 写 入 时 ， callback 回调 函数 将 会 被 执行 ， 但 可 能 不 会 马上 执行 。 


socket.end([data][, encoding]) 


半 关 闭 一 个 socket 。 比 如 ， 它 发 送 一 个 FIN 报 文 。 可 能 服务 器 仍然 在 发 送 一 些 
数据 。 


如 果 data 参数 被 指定 ， 那 么 等 同 于 先 调用 socket.write(data, encoding) ， 
再 调用 socket.end() ° 

socket.destroy() 

确保 这 个 socket 上 没有 IO 活动 发 生 。 只 在 发 生 错 误 情 况 才 需要 (如 处 理 错 

误 ) 。 

socket.pause() 


暂停 数据 读 取 。 data 事件 将 不 会 再 触发 。 对 于 控制 上 传 非常 有 用 。 


socket.resume() 


用 于 在 调用 pause() 后 ， 恢 复数 据 读 取 。 


socket.setTimeout(timeout[, callback]) 


如 果 socket 在 timeout 毫秒 中 没有 活动 后 ， 设 置 其 为 超时 。 默 认 情 况 
下 ， net.Socket 没有 超时 。 


当 超 时 发 生 ， socket 会 收 到 一 个 timeout 事件 ， 但 是 连接 将 不 会 被 断 开 。 用 户 
必须 手动 地 调用 end() 或 destroy() 方法 。 


如 果 timeout Æ 0 ， 那 么 现 有 的 超时 将 会 被 禁用 。 
可 选 的 callback 参数 就 会 被 自动 添加 为 timeout 事件 的 监听 器 。 


返回 一 个 socket 。 


socket.setNoDelay([noDelay]) 


警 用 纳 格 算法 (Nagle algorithm) 。 默 认 情 况 下 TCP 连 接 使 用 纳 格 算法 ， 它 们 的 数 
据 在 被 发 送 前 会 被 缓存 。 设 置 noDelay 为 true 将 会 在 每 
次 socket ,write() 时 立刻 发 送 数据 。 noDelay 默认 为 true 。 


返回 一 个 socket 。 


socket.setKeepAlive([enable][, initialDelay]) 


启用 / 警 用 长 连接 功能 ， 并 且 在 第 一 个 在 闲置 socket 的 长 连接 probe 被 发 送 前 ， 
可 选 得 设置 初始 延 时 。 enable 默认 为 false 。 


设 定 initialDelay (毫秒 )， 来 设 定 在 收 到 的 最 后 一 个 数据 包 和 第 一 个 长 连 
接 probe 之 间 的 延 时 。 将 initialDelay 设 成 0 会 让 值 保 持 不 变 (默认 值 或 之 前 
所 设 的 值 ) 。 黑 认为 0 。 


返回 一 个 socket 。 


socket.address() 


返回 绑 定 的 地 址 ， 协 议 族 名 和 端口 通过 操作 系统 报告 。 对 查找 操作 系统 分 配 的 地 址 
哪个 端口 被 分 配 非常 有 用 。 返 回 一 个 有 三 个 属性 的 对 象 。 如 { port: 12346, 
family: 'IPv4', address: '127.0.0.1' } ° 


socket.unref() 


调用 一 个 socket 对 象 的 unref 方法 将 允许 如 果 它 是 事件 系统 中 唯一 活跃 
的 socket ， 程 序 将 会 退出 。 如 果 socket 已 经 被 调用 过 这 个 方法 ， 那 么 再 次 调 
用 这 个 方法 将 不 会 有 任何 效果 。 


返回 socket 对 象 。 


socket.ref() 


与 unref 相反 ， 在 一 个 已 经 被 调用 unref 方法 的 socket 中 调用 ref Aix > AB 
么 如 果 它 是 唯一 活跃 的 socket 时 ， 程 序 将 不 会 退出 (RU) o WX socket 已 
经 被 调用 过 这 个 方法 ， 那 么 再 次 调用 这 个 方法 将 不 会 有 任何 效果 。 


返回 socket 对 象 。 


socket.remoteAddress 


远程 I|P 地 址 字符 串 。 例 如 ， '74,125.127.100' 或 '2001:4860:a005::68' ° 


socket.remoteFamily 


远程 |IP 协 议 族 字符 串 。 例 如 ， 'IPv4' 或 'IPV6' 。 


socket.remotePort 


远程 端口 数值 。 例 如 ， 80 或 21 © 


socket.localAddress 

远程 客户 端正 连接 的 本 地 |P 地 址 字符 事 。 例 如 ， 如 果 你 正在 监听 '0.0.0.0' 并 且 
客户 端 连 接 在 '192.168.1.1' ， 其 值 将 为 '192.168.1.1' ° 
socket.localPort 


本 地 端口 数值 。 例 如 ， go 或 21 。 


socket.bytesRead 


接受 的 字 节 数 。 


socket.bytesWritten 

发 送 的 字 节 数 。 

net.Socket net.Socket 实例 是 一 个 包含 以 下 事件 
的 EventEmitter 

Event: ‘lookup’ 

在 解析 主机 名 后 ， 连 接 主机 前 触发 。 对 UNIX socket 不 适用 。 


e err {Error | Null} 错误 对 象 ， 参 阅 dns.lookup() 
e address {String} IP 地 址 
e family {String | Null} 地 址 类 型 。 参 阅 'dns.lookup() 


Event: ‘connect' 


在 socket 连接 成 功 建立 后 触发 。 参 阅 connect() ° 


Event: ‘data’ 
e Buffer object 


在 接受 到 数据 后 触发 。 参 数 将 会 是 一 个 Buffer 或 一 个 字符 串 。 数 据 的 编码 
由 socket.setEncoding() 设置 (更 多 详细 信息 请 查看 可 读 流 章节 ) © 


注意 ， 当 socket 触发 data 事件 时 ， 如 果 没 有 监听 器 和 存在。 那么 数据 将 会 丢 
失 。 

Event: end 

当 另 一 端的 socket 发 送 一 个 FIN 报 文 时 触发 。 


默认 情况 ( allowHalfOpen == false ) 下 ， 一 旦 一 个 socket 的 文件 描述 符 被 
从 它 的 等 待 写 队 列 (pending write queue) 中 写 出 ， socket 会 销毁 它 。 但 是 ， 当 
设 定 allowHalfopen == true 后 ， socket 不 会 在 它 这 边 自动 调用 end() ， 允 
许 用 户 写 入 任意 数量 的 数据 ， 需 要 注意 的 是 用 户 需 要 在 自己 这 边 调用 end() ° 


Event: timeout 


当 socket 因 不 活动 而 超时 时 触发 。 这 只 是 来 表示 socket 被 限制 。 用 户 必 须 手 
动 关 闭 连接 。 


参阅 socket.setTimeout() ° 


Event: ‘drain’ 
当 写 缓冲 为 空 时 触发 Q 可 以 被 用 来 控 制 上 传 流量 Q 


参阅 socket.write() 的 返回 值 。 


Event: ‘error’ 


e Error object 


当 发 生 错 误 时 触发 。 close 事件 会 紧 跟 着 这 个 事件 触发 。 


Event: ‘close’ 
e had_error 如 果 socket 有 一 个 传输 错误 时 为 true 
当 socket 完全 关闭 时 触发 。 参 数 had error 是 一 个 表示 socket 是 否 是 因为 传 
输 错 误 而 关闭 的 布尔 值 。 
net.isIP(input) 


一 个 IP 地 址 。 如 果 是 不 合法 字符 囊 时 ， 会 返回 0 。 如 果 是 IPv4 
IPv6 地 址 则 返回 6 。 


测试 input 是 否 


是 
地 址 则 返回 4 ， 是 


net.isIPv4(input) 
如 果 input 有 是 一 个 IPv4 地 址 则 返回 true > SMR false 。 


net.isIPv6(input) 


如 果 input 是 一 个 IPv6 地 址 则 返回 true » SMA false 。 


OS 


(C2 -e 
提供 一 些 基本 的 操作 系统 相关 的 功能 。 


使 用 require('os') 来 获得 这 个 模块 。 


os.tmpdir() 


返回 操作 系统 默认 的 临时 文件 目录 。 


os.homedir() 


返回 当前 用 户 的 家 目录 。 


os.endianness() 


返回 CPU 的 字 节 序 。 BE 为 大 端 字 节 序 ， LE 为 小 端 字 节 序 。 


os.hostname() 


返回 当前 操作 系统 的 主机 名 。 


os.type() 

返回 操作 系统 名 。 例 如 ，Linux 下 为 'Linux' ，OS XT 下 为 'Darwin' > Windows 
下 为 'Windows_NT' 。 

os.platform() 


返回 操作 系统 平台 。 可 能 的 值 
有 'darwin' ° 'freebsd' > '‘linux' ， 'sunos' 或 'win32' 。 返 


回 process.platform 值 。 


os.arch() 


返回 操作 系统 CPU 架构 。 可 能 的 值 有 'x64' > ‘arm' Fe 'ia32' 。 返 
回 process.arch 值 。 
os.release() 


返回 操作 系统 的 发 行 版 本 。 


os.Uptime() 


返回 操作 系统 的 运行 时 间 ( 秒 ) 。 


os.loadavg() 
返回 一 个 包含 1，5，15 分 钟 平均 负载 的 数组 。 


平均 负载 是 一 个 系统 活动 测量 ， 由 操作 系统 计算 并 且 由 一 个 分 数 表示 。 根 据 经 验 ， 
理想 的 负载 均衡 数 应 该 比 系 统 的 逻辑 CPU 数 小 。 


平均 负载 完全 是 一 个 UNIX-y 概念 ; 在 Windows 中 没有 完全 对 等 的 概念 。 所 以 在 
Windows F > &*+ 82% 24H [0, 0, 0] ° 
os.totalmem() 


以 字 节 的 形式 返回 系统 的 总 内 存 。 


os.freemem() 


以 字 节 的 形式 返回 系统 的 可 用 内 存 。 


os.cpus() 


返回 一 个 包含 安装 的 各 个 CPU/ 核 心 信 息 的 对 象 数 组 : 型 号 ， 速 度 (单位 MHz) ， 
和 时 间 (一 个 包含 CPU/ 核 心 花 费 的 毫秒 数 的 对 


象 : user ° nice ， sys ， idle 和 irq ) ° 
os.cpus 例子 : 
[ { model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz', 


speed: 2926, 
times: 


{ user: 252020, 


nice: 0, 
sys: 30340, 
idle: 1070356870, 
Lrg: (0 
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz', 
speed: 2926, 
times: 
{ user: 306960, 
nice: 0, 
sys: 26980, 
idle: 1071569080, 
irq: @ >} py 
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz', 
speed: 2926, 
times: 
{ user: 248450, 
nice: 0, 
sys: 21750, 
idle: 1070919370, 
ing: 0 } }, 
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz', 
speed: 2926, 
times: 
{ user: 256880, 
nice: 0, 
sys: 19430, 
idle: 1070905480, 
irq: 20°} }, 
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz', 
speed: 2926, 
times: 
{ user: 511580, 
nice: 20, 
sys: 40900, 
idle: 1070842510, 
ing: 0 } }, 
{ model: 'Intel(R) Core(TM) i7 CPU 860 @ 2.80GHz', 
speed: 2926, 
times: 


203 


{ user: 291660, 
nice: 0, 
sys: 34360, 
idle: 1070888000, 
ang: 10°} Pr 

{ model: 'Intel(R) Core(TM) i7 CPU 

speed: 2926, 

times: 

{ user: 308260, 
nice: 0, 
sys: 55410, 
idle: 1071129970, 
irq: 880 } }, 

{ model: 'Intel(R) Core(TM) i7 CPU 

speed: 2926, 

times: 

{ user: 266450, 
nice: 1480, 
sys: 34920, 
idle: 1072572010, 
irq: 30 } } ] 


注意 因为 nice 值 是 UNIX 中 心 的 ， 所 以 在 Windows 中 所 有 进程 的 nice 值 都 将 


日 


元 0 ° 


os.networklnterfaces() 


获取 一 个 网 络 接口 列表 : 


860 @ 2.80GHz', 


860 @ 2.80GHz', 


{ lo: 

[ { address: 1127.0017, 
netmask: '255.0.0.0', 
family: 'IPv4', 
mac: '00:00:00:00:00:00", 
internal: true }, 

{ address: '::1', 
netmask ann a e E 
family: 'IPv6', 
mac: '00:00:00:00:00:00', 
internal: true } ], 

etho: 

[ { address: '192.168.1.108', 
netmask: 2557255255 0i 
family: 'IPv4', 
mac: '01:02:03:0a:0b:0c', 
internal: false }, 

{ address: 'fe80::a00:27ff:fe4e:66a1', 
netmask: un tii 
family: 'IPv6', 
mac: '01:02:03:0a:0b:0c', 
internal: false } ] } 


注意 ， 由 于 底层 系统 实现 的 原因 ， 它 将 只 会 返回 被 赋予 一 个 地 址 的 网 络 接口 。 


os.EOL 


一 个 定义 了 对 于 操作 系统 ， 合 适 的 行 结束 记号 的 常量 。 


Path 


PER: 2 -F2 


这 个 模块 提供 了 处 理 和 转换 文件 路 径 的 工具 。 几 乎 所 有 的 方法 都 仅 提 供 字 符 串 转换 
功能 。 文 件 系统 不 会 去 检查 路 径 是 否 可 用 。 


通过 require('path') 来 使 用 这 个 模块 。 以 下 是 提供 的 方法 : 


path.normalize(p) 
规范 化 字符 串 路 径 ， 注 意 '..' 和 '.' 部 分 。 


当 有 多 个 连续 斜 枉 时 ， 它 们 会 被 替换 为 一 个 斜 杠 ; 当 路 径 的 最 后 有 一 个 斜 枉 ， 它 会 
被 保留 。 在 Windows 下 使 用 反 儿 杠 。 


例子 : 
path.normalize('/foo/bar//baz/asdf/quux/..') 


// returns 


'/Ffoo/bar/baz/asdf ' 


path.join([path1][, path2][, ...]) 
连接 所 有 的 参数 ， 并 且 规范 化 结果 路 径 。 


参数 必须 是 字符 串 。 在 0.8 版 本 中 ， 非 字符 串 参 数 会 被 忽略 ， 在 0.10 版 本 及 之 后 ， 会 
抛 出 一 个 异常 。 


例子 : 


pathejoun( oo bay, baz/asdn a GUUX 7 an) 
// returns 
'/Ffoo/bar/baz/asdf ' 


path. join( foe 7 {}, "bar ) 
// throws exception 
TypeError: Arguments to path.join must be strings 


path.resolve([from ...], to) 
将 to 解析 为 绝对 路 径 。 


如 果 to 不 已 经 是 相对 于 from 参数 的 绝对 路 径 ， to 会 被 添加 到 from HA 
边 ， 直 到 找 出 绝对 了 路 径 。 如 果 使 用 了 from 中 所 有 的 路 径 仍 没有 找 出 绝对 路 径 ， 
当前 的 工作 路 径 也 会 被 使 用 。 结 果 路 径 会 被 规范 化 ， 并 且 结 尾 的 斜 杠 会 被 移 除 ， 除 
非 解析 得 到 了 一 个 根 路 径 。 非 字符 串 参 数 会 被 忽略 。 


另 一 个 思路 是 将 它 看 做 shell 中 一 系列 的 cd 命令 : 


path.resolve('foo/bar', '/tmp/file/', '..', ‘a/../subfile') 
相似 于 : 

cd foo/bar 

cd /tmp/file/ 

Cul or 

cd a/../subfile 

pwd 


区 别 是 不 同 的 路 径 不 需要 一 定 存在 ， 并 且 可 以 是 文件 。 


例子 : 


path.resolve('/foo/bar', './baz') 
// returns 
'/Ffoo/bar/baz' 


path.resolve('/foo/bar', '/tmp/file/' ) 
// returns 
'/tmp/file' 


path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif') 
// if currently in /home/myself/iojs, it returns 
'/home/myself/iojs/wwwroot/static_files/gif/image.gif' 


path.isAbsolute(path) 


判断 path 是 否 是 一 个 绝对 路 径 。 一 个 绝对 路 径 总 是 被 解析 为 相同 的 路 径 ， 无 论 当 
前 工作 目录 是 哪里 。 


Posix 例 子 : 


path.isAbsolute('/foo/bar') // true 
path.isAbsolute('/baz/..') // true 


path.isAbsolute('qux/' ) // false 
path.isAbsolute('.') // false 
Windowst] + : 


path.isAbsolute('//server') // true 
path.isAbsolute('C:/foo/..') // true 
path.isAbsolute('bar\\baz' ) // false 
path.isAbsolute('.') // false 


path.relative(from, to) 
解析 从 from 到 to 的 相对 路 径 


当 我 们 有 两 个 绝对 路 径 ， 并 且 我 们 要 得 到 它们 间 一 个 对 于 另 OU 
实际 上 是 path.resolve 的 相反 操作 。 我 们 可 以 看 看 这 是 什么 意思 : 


path.resolve(from, path.relative(from, to)) == path.resolve(to) 


例子 : 


path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb' 
) 


// returns 
-moo 


path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb' 
) 


// returns 
Be) 2a LMU DOD 


path.dirname(p) 

返回 路 径 的 目录 名 。 与 Unix dirname 命令 相似 。 

例子 : 
path.dirname('/foo/bar/baz/asdf/quux') 


// returns 
'/foo/bar/baz/asdf' 


path.basename(p[, ext]) 
返回 路 径 中 的 最 后 一 部 分 。 与 Unix basename 命令 相似 。 
例子 : 

path. basename('/foo/bar/baz/asdf/quux.html' ) 


// returns 
"quux.html' 


path. basename('/foo/bar/baz/asdf/quux.html', '.html') 
// returns 
' quux ' 


path.extname(p) 


返回 路 径 的 扩展 名 ， 即 从 路 径 的 最 后 一 部 分 中 的 最 后 一 个 !.' 到 末尾 之 间 的 字符 
串 。 如 果 路 径 的 最 后 一 部 分 没有 ',' ， 或 者 第 一 个 字符 是 ',， ， 那 么 将 返回 一 个 


空 字符 串 ， 例 子 : 


path.extname('index.html') 
// returns 
Pein 


path.extname('index.coffee.md' ) 
// returns 
Ue trio? 


path.extname('index.') 
// returns 


path.extname('index' ) 
// returns 


path.sep 

BOLE SY LAD NN 或 '/1 e 

一 个 *nix 上 的 例子 : 
'foo/bar/baz'.split(path.sep) 


// returns 
[foo bar’, “baz 


一 个 Windows 上 的 例子 : 


'foo\\bar\\baz'.split(path.sep) 
// returns 
[toot “bar. baz || 


path.delimiter 
特定 平台 的 路 径 分 隔 符 ，';' 或 ':' 。 


一 个 *nix 上 的 例子 : 


console.log(process.env.PATH) 
-VUusrADimn /bn /USii7 Sbalns, Sbilnia/ US local/ bain: 


process.env.PATH.split(path.delimiter ) 
// returns 
[7Usr/ bil, De 2 7USh/Sbin, -/sbin., )7uUSh/ Local? hin *] 


一 个 Windows 上 的 例子 : 


console.log(process.env.PATH) 
// 'C:\Windows\system32;C:\Windows;C:\Program Files\iojs\' 


process.env.PATH.split(path.delimiter ) 

// returns 

['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\ioj 
s\\'] 


path.parse(pathString) 
根据 一 个 路 径 字符 串 返 回 一 个 对 象 。 


一 个 *nix 上 的 例子 : 


path.parse('/home/user/dir/file.txt') 
// returns 


{ 
rook 2 7" 
dir : "/home/user/dir", 
base : "file.txt", 
EXE .EXE 
name : "file" 


一 个 Windows 上 的 例子 : 


path.parse('C:\\path\\dir\\index.htm1' ) 
// returns 


{ 
root ACEN 
dir = “C:\\path\\dir™, 
base : "index.html", 
ext 0 shims; 
name : "index" 

} 


path.format(pathObject) 


根据 一 个 对 象 ， 返 回 一 个 路 径 字符 串 ， 与 path.parse WA ° 


path.format({ 


root iR 

dir : "/home/user/dir", 
base : "file.txt", 

ext : "txt", 

name : "file" 


}) 


// returns 
"/home/user/dir/file.txt' 


path.posix 
提供 对 上 述 的 路 径 方 法 的 访问 ， 但 是 总 是 以 兼容 posix 的 方式 交互 (interact) ° 


path.win32 


提供 对 上 述 的 路 径 方法 的 访问 ， 但 是 总 是 以 兼容 Win32 的 方式 交互 (interact) 。 


process 


process 对 象 是 一 个 全 局 对 象 ， 并 且 何 以 被 在 任何 地 方 调用 。 这 是 一 
个 EventEmitter 实例 。 


Exit Codes 


SAE AD REE SATA > node.js 通常 将 会 以 一 个 0 为 退出 码 退 出 。 以 下 这 
些 状 态 码 会 在 其 他 情况 下 被 用 到 : 


o 1 未 捕获 的 致命 异常 。 这 是 一 个 未 捕获 的 异常 ， 并 且 它 没有 被 domain 处 理 ， 
也 没有 被 uncaughtException 处 理 。 

e 2 未 使 用 (由 Bash 为 内 建 误 操作 保留 ) 。 

e 3 内 部 的 JavaScript 解析 错误 。 node. Je 内 部 的 JavaScript 源码 引导 
(bootstrapping) 造成 的 一 个 解释 错误 。 这 极其 罕见 。 并 且 常 常 只 会 发 生 
在 node.js 自身 的 开发 过 程 中 。 

e 4 内 部 的 JavaScript 求 值 错误 。 node.js 内 部 的 JavaScript 源码 引导 
(bootstrapping) 未 能 在 求 值 时 返回 一 个 函数 值 。 这 极其 罕见 。 并 且 常 常 只 会 
发 生 在 node.js 自身 的 开发 过 程 中 。 

o 5 致命 错误 。 这 是 V8 中 严重 的 不 可 恢复 的 错误 。 典 型 情况 下 ， 一 个 带 有 FATAL 
ERROR 前 级 的 信息 会 被 打印 在 stderr ° 

© 6 内 部 异常 处 理 函 数 丧 失 功 能 。 这 是 一 个 未 捕获 异常 ， 但 是 内 部 的 致命 异常 处 
理 函 数 被 设置 为 丧失 功能 ， 并 且 不 能 被 调用 。 

e 7 内 部 异常 处 理 函 数 运行 时 失败 。 这 是 一 个 未 捕获 异常 ， 并 且 内 部 致命 异常 处 
理 函 数 试 图 处 理 它 时 ， 自 身 抛 出 了 一 个 错误 。 例 如 它 可 能 在 
4 process.on('uncaughtException') 或 domain.on('error') #2 83% 
抛 出 错误 时 发 生 。 

e 8 未 使 用 。 node.js 的 之 前 版 本 中 ， 退 出 码 8 通常 表示 一 个 未 捕获 异常 。 

e 9 无 效 参 数 。 当 一 个 位 置 的 选项 被 指定 ， 或 者 一 个 必 选 的 值 没 有 被 提供 。 

e 10 内 部 的 JavaScript 运行 时 错误 。 node.js 内 部 的 JavaScript 源码 引 
导 (bootstrapping) 有 函数 被 调用 时 抛 出 一 个 错误 。 这 极其 罕见 。 并 且 人 常常 只 会 
发 生 在 node.js 自身 的 开发 过 程 中 。 

e。 12 无 效 的 调试 参数 。 --debug 和 /或 --debug-brk 选项 被 设置 ， 当 时 选择 
了 一 个 无 效 的 端口 。 

e 大 于 128 信号 退出 。 如 果 node.js 收 到 了 一 个 如 SIGKILL 或 SIGHUP 的 至 


命 信号 ， 那 么 它 将 以 一 个 128 加 上 信号 码 的 值 的 退出 码 退 出 。 这 是 一 个 标准 
的 Unix 实 践 ， 因 为 退出 码 由 一 个 7 位 整数 定义 ， 并 且 信 号 的 退出 设置 了 一 个 高 
顺序 位 (high-order bit) ， 然 后 包含 一 个 信号 码 的 值 。 


Event: ‘exit' 


进程 即将 退出 时 触发 。 在 这 个 时 刻 已 经 没有 办 法 可 以 阻止 事件 循环 的 退出 ， 并 且 一 
BPA A exit 监听 器 运行 结束 时 ， 进 程 将 会 退出 。 因 此 ， 在 这 个 监听 器 中 你 仅仅 
能 调用 同步 的 操作 。 这 是 检查 模块 状态 (如 单元 测试 ) 的 好 钩子 。 回 调 函 数 有 一 个 
退出 码 参 数 。 


例子 : 


process.on('exit', function(code) { 
17 dee Nel CO ES 
setTimeout(function() { 
console.log('This will not run'); 


J 9); 


console.log('About to exit with code:', code); 


}); 


Event: 'beforeExit' 


这 个 事件 在 node.js 清空 了 它 的 事件 循环 并 且 没 有 任何 已 安排 的 任务 时 触发 。 
常 node.js 当 没 有 更 多 被 安排 的 任务 时 就 会 退出 ， 但 是 beforeExit e 
异步 调用 ， 让 node.js 继续 运行 。 


beforeExit 在 程序 被 显示 终止 时 不 会 触发 ， 如 process.exit() 或 未 捕获 的 异 
常 。 除 非 想 去 安排 更 多 的 任务 ， 否 则 它 不 应 被 用 来 做 为 exit 事件 的 替代 。 
Event: 'uncaughtException’ 


当 一 个 异常 冒 泡 回 事件 循环 时 就 会 触发 。 如 果 这 个 时 间 被 添加 了 监听 器 ， 那 么 默认 
行为 (退出 程序 且 打 印 堆栈 跟踪 信息 ) 将 不 会 发 生 。 


例子 : 


process.on('uncaughtException', function(err) { 
console.log('Caught exception: ' + err); 


3); 


setTimeout(function() { 
console.log('This will still run.'); 
}, 500); 


// Intentionally cause an exception, but don't catch it. 
nonexistentFunc(); 
console.log('This will not run.'); 


注意 ， uncaughtException 来 处 理 异 常 是 非常 粗糙 的 。 


请 不 要 使 用 它 ， 使 用 domain 来 替代 。 如 果 你 已 经 使 用 了 它 ， 请 在 不 处 理 这 个 异常 
之 后 重启 你 的 应 用 。 


请 不 要 像 node.js 的 Error Resume Next 这 样 使 用 。 一 个 未 捕获 异常 意味 着 你 
的 应 用 或 拓展 有 未 定义 的 状态 。 盲 目地 恢复 意味 着 任何 事 都 可 能 发 生 。 


想 oe - 电源 被 拉 断 了 。10 次 中 前 9 次 都 没有 问题 ， 但 是 第 10 次 
By > WR aD AA eA ait 


你 已 经 被 警告 。 


Event: 'unhandledRejection' 


在 一 个 事件 循环 中 ， 当 一 个 promise tk 4B" LAA HtA hg IRAE HA Ab 
发 。 当 一 个 带 有 promise 异常 的 程序 被 封装 为 被 “拒绝 "的 promise 时 ， 这 样 的 程 
序 的 错误 可 以 被 promise.catch(...) 捕获 处 理 并 且 "“ 拒 绝 "会 通过 promise 4% H 
泡 。 这 个 事件 对 于 侦 测 和 保持 追踪 那 些 “ 拒 绝 " 没 有 被 处 理 的 promise 非常 有 用 。 
这 个 事件 会 带 着 以 下 参数 触发 : 


e reason promise 的 “拒绝 ?对象 (通常 是 一 个 错误 实例 ) 
e p 被 “拒绝 ”的 promise 


下 面 是 一 个 把 所 有 未 处 理 的 “拒绝 ”打印 到 控制 台 的 例子 : 


process.on('unhandledRejection', function(reason, p) { 
console.log("Unhandled Rejection at: Promise ", p, " reason: 
", reason); 
// application specific logging, throwing an error, or other 
logic here 


}); 


下 面 是 一 个 会 触发 unhandledRejection 事件 的 “拒绝 ”: 


somePromise.then(function(res) { 
return reportToUser(JSON.pasre(res)); // note the typo 
aie A nO seeren Or then” 


Event: 'rejectionHandled' 


当 一 个 Promise 被 “拒绝 "并且 一 个 错误 处 理 函 数 被 附 给 了 它 (如 .catch() ) 时 
的 下 一 个 事件 循环 之 后 触发 。 这 个 事件 会 带 着 以 下 参数 触发 : 


e Pp 一 个 在 之 前 会 被 触发 在 unhandledRejection 事件 中 ， 但 现在 被 处 理 函 数 
捕获 的 promise 


一 个 promise 链 的 顶端 没有 “拒绝 ”可 以 总 是 被 处 理 的 概念 。 由 于 其 异步 的 本 质 ， 
一 个 promise 的 “拒绝 ?可 以 在 未 来 的 某 一 个 时 间 点 被 处 理 ， 可 以 是 在 事件 循环 中 
被 触发 unhandledRejection 事件 之 后 。 


另外 ， 不 像 同步 代码 中 是 一 个 永远 增长 的 未 捕获 异常 列表 ， promise 中 它 是 一 个 
可 伸缩 的 未 捕获 拒绝 列表 。 在 同步 代码 中 ， uncaughtException 事件 告诉 你 
未 捕获 异常 列表 增长 了 。 但 是 在 promise 中 ， unhandledRejection 事件 告诉 
你 未 捕获 “拒绝 ”列表 增长 了 ， rejectionHandled 事件 告诉 你 未 捕获 “拒绝 ”列表 
缩短 了 。 


使 用 "拒绝 ? 侦 测 钧 子 来 保持 一 个 被 “拒绝 "的 promise 列表 : 


var unhandledRejections = []; 

process.on('unhandledRejection', function(reason, p) { 
unhandledRejections.push(p); 

J); 


process.on('rejectionHandled', function(p) { 
var index = unhandledRejections.indexOf(p); 
unhandledRejections.splice(index, 1); 


}); 


Signal Events 
当 一 个 进程 收 到 一 个 信号 时 触发 。 参 阅 sigaction(2) ° 


监听 SIGINT 信号 的 例子 


// Start reading from stdin so we don't exit. 
process.stdin.resume(); 


process.on('SIGINT', function() { 
console.log('Got SIGINT. Press Control-D to exit.'); 


}); 


一 个 发 送 SIGINT 信号 的 快捷 方法 是 在 大 多 数 终端 中 按 下 Control-C ° 
注意 : 


人 启 调试 的 保留 信号 。 可 以 为 其 添加 一 个 监听 
， 但 不 能 阻止 调试 的 开始 。 

e SIGTERM 和 SIGINT 在 非 Windows 平 台 下 有 在 以 128 + 信号 退出 码 退 出 前 重 

置 终端 模式 的 默认 监听 器 。 如 果 另 有 监听 器 被 添加 ， 默 认 监 听 器 会 被 移 除 

(BP node.js 将 会 不 再 退出 ) 。 
e SIGPIPE 默认 被 忽略 ， 可 以 被 添加 监听 器 。 
e SIGHUP 当 控 制 台 被 关闭 时 会 在 Windows 中 产生 ， 或 者 其 他 平台 有 其 他 相似 情 
况 时 (AA signal(7) ) 。 它 可 以 被 添加 监听 器 ， 但 是 Windows 
中 node.js 会 无 条 件 的 在 10 秒 后 关闭 终端 。 在 其 他 非 Windows 平 台 ， 它 的 默 
认 行 为 是 结束 node.js ， 但 是 一 旦 被 添加 了 监听 器 ， 默 认 行 为 会 被 移 除 。 
SIGTERM 在 Windows 中 不 被 支持 ， 它 可 以 被 监听 。 
SIGINT 支持 所 有 的 平台 。 可 以 由 CTRL+C 产生 (尽管 它 可 能 是 可 配置 的 ) 。 


当 启 用 终端 的 raw mode 时 ， 它 不 会 产生 。 

e SIGBREAK 在 Windows 中 ， 按 下 CTRL+BREAK 时 它 会 产生 。 在 非 Windows 
平台 下 ， 它 可 以 被 监听 ， 但 它 没有 产生 的 途径 。 

。 SIGWINCH 当 终 端 被 改变 大 小 时 产生 。Windows 下 ， 它 只 会 在 当 光 标 被 移动 
时 写 入 控制 台 或 可 读 tty 使 用 raw mode 时 发 生 。 

e SIGKILL 可 以 被 添加 监听 器 。 它 会 无 条 件 得 在 所 有 平台 下 关闭 node.js ° 

e SIGSTOP 可 以 被 添加 监听 器 。 


注意 Windows 不 支持 发 送信 号 ， 但 node.js 通 

过 process.kill() 和 child_process.kill() 提供 了 模拟 : -发 送信 号 0 被 
用 来 检查 进程 的 存在 - 发 送 SIGINT，SIGTERM 和 SIGKILL 会 导致 目标 进程 的 无 
条 件 退 出 

process.stdout 

一 个 指向 stdout 的 可 写 流 。 

例如 ， console.log 可 能 与 这 个 相似 : 


console.log = function(msg) { 
process.stdout.write(msg + '\n'); 


Po 


在 node.js ¥ > process.stderr 和 process.stdout 与 其 他 流 不 同 ， 因 为 他 
们 不 能 被 关闭 (调用 end() 会 报错 ) 。 它 们 永远 不 触发 finish 事件 并 且 写 操作 
前 常 是 阻塞 的 。 


o 当 指 向 首 通 文件 或 TTY 文 件 描述 符 时 ， 它 们 是 阻塞 的 。 
o 以 下 情况 下 他 们 指向 流 


o 他 们 在 Linux/Unix 中 阻塞 
o 他 们 在 Windows 中 的 其 他 流 里 不 阻塞 


若 要 检查 node.js 是 否 在 一 个 TTY 上 下 文中 运行 ， 读 
取 process.stderr ， process.stdout 或 process.stdin 的 isTTY 属性 : 


$ iojs -p "Boolean(process.stdin.isTTY)" 

true 

$ echo "foo" | iojs -p "Boolean(process.stdin.isTTY)" 
false 


$ iojs -p "Boolean(process.stdout.isTTY)" 

true 

$ iojs -p "Boolean(process.stdout.isTTY)" | cat 
false 


更 多 信息 请 参阅 tty 文 档 。 


process.stderr 
一 个 指向 stderr 的 可 写 流 。 


在 node.js 中 ， process.stderr 和 process.stdout 与 其 他 流 不 同 ， 因 为 他 
们 不 能 被 关闭 (调用 end() 会 报错 ) 。 它 们 永远 不 触发 finish 事件 并 且 写 操作 
通常 是 阻塞 的 。 


o 当 指 向 普通 文件 或 TTY 文 件 描述 符 时 ， 它 们 是 阻塞 的 。 
e 以 下 情况 下 他 们 指向 流 
o 他 们 在 Linux/Unix 中 阻塞 
o 他 们 在 Windows 中 的 其 他 流 里 不 阻塞 
process.stdin 
一 个 指向 stdin 的 可 读 流 。 


一 个 打开 标准 输入 并 且 监 听 两 个 事件 的 例子 : 


process.stdin.setEncoding('utf8'); 


process.stdin.on('readable', function() { 
var chunk = process.stdin.read(); 


if (chunk !== null) { 
process.stdout.write('data: ' + chunk); 
} 
}); 


process.stdin.on('end', function() { 
process.stdout.write('end'); 


}); 
作为 一 个 流 ， process.stdin 可 以 被 切换 至 “上 昌 ” 模 式 ， 这 样 就 可 以 兼 
X node.js v0.10 前 所 写 的 脚本 。 更 多 信息 请 参阅 流 的 兼容 性 。 


ERAP stdin 流 默 认 是 被 暂停 的 。 所 以 你 必须 调 
用 process.stdin.resume() 来 读 取 。 注 意 调 用 process.stdin.resume() 这 


个 操作 本 身 也 会 将 流 切 换 至 昌 模 式 。 


如 果 你 正 将 开启 一 个 新 的 工程 。 你 应 该 要 更 常 使 用 “新 "模式 的 流 。 


process.argv 


含 了 命令 行 参数 的 数组 。 第 一 次 元 素 将 会 是 'iojs' ， 第 二 个 元 素 将 会 
是 JavaScript 文件 名 。 之 后 的 元 素 将 会 是 额外 的 命令 行 参 数 。 


// print process.argv 
process.argv.forEach(function(val, index, array) { 
console.log(index + ': ' + val); 


$ iojs process-2.js one two=three four 


0: iojs 
1: /Users/mjr/work/iojs/process-2.js 
2: one 
3: two=three 
4: four 
process.execPath 


这 将 是 开局 进程 的 可 执行 文件 的 绝对 路 径 名 : 
例子 : 


/usr/local/bin/iojs 


process.execArgv 


这 是 在 局 ell ean 文 些 参数 不 会 出 现 
在 process. 中 ， 并 且 不 会 包含 node.js 可 执行 文件 ， 脚 本 名 和 其 他 脚本 名 
之 后 的 参数 。 这 些 参数 对 开启 和 父 Pierer 于 环境 的 子 进程 非常 有 用 。 


例子 : 


$ iojs --harmony script.js --version 


process.execArgv 将 会 是 : 


['--harmony'] 


process.argv 将 会 是 : 


["/usr/local/bin/iojs', 'script.js', '--version'] 


process.abort() 


这 将 导致 node.js 触发 abort 事件 。 这 个 将 导致 node.js 退出 ， 并 创建 一 个 核 
SL 


process.chdir(directory) 


为 进程 改变 当前 工作 目录 ， 如 果 失 败 ， 则 抛 出 一 个 异常 。 


console.log('Starting directory: ' + process.cwd()); 


try { 
process.chdir('/tmp'); 


console.log('New directory: ' + process.cwd()); 


} 
catch (err) { 


console.log('chdir: ' + err); 


process.cwd() 


返回 进程 的 当前 工作 目录 。 


console.log('Current directory: ' + process.cwd()); 


process.env 
包含 用 户 环境 变量 的 对 象 。 参 阅 environ(7) ° 


一 个 例子 : 


{ TERM: 'xterm-256color', 
SHELL: '/usr/local/bin/bash', 
USER: 'maciej', 
PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin', 
PWD: '/Users/maciej', 
EDITOR: 'vim', 
SHLVL: '1', 
HOME: '/Users/maciej', 
LOGNAME: 'maciej', 
'/usr/local/bin/iojs' } 


你 可 以 改写 这 个 对 象 ， 但 是 改变 不 会 反应 在 你 的 进程 之 外 。 这 以 为 着 以 下 代码 不 会 
正常 工作 : 


$ iojs -e 'process.env.foo = "bar"' && echo $foo 
但 是 以 下 代码 会 : 
process.env.foo = ‘'bar'; 


console.log(process.env.foo); 


process.exit([code]) 
使 用 指定 的 退出 码 退 出 程序 ， 如 果 忽 略 退出 码 。 那 么 将 使 用 "成 功 " 退 出 码 9 。 
以 一 个 “失败 ”退出 码 结 


process.exit(1); 


在 执行 node.js 的 shell 中 可 以 看 到 为 1 的 退出 码 。 


process.exitCode 


将 是 程序 退出 码 的 数字 ， 当 程序 优雅 退出 或 被 process,exit() 关闭 且 没 有 指定 
出 


退出 码 时 。 

为 process.exit(code) 指定 一 个 退出 码 会 覆盖 之 前 的 process.exitCode i 

Bo 

process.getgid() 

注意 : 这 个 函数 只 在 POSIX 平 台 上 有 效 (如 在 Windows，Android 中 无 效 ) ° 

获取 进程 的 群 组 标识 (参阅 getgid(2) ) 。 这 是 一 个 群 组 id 数组 ， 不 是 群 组 名 。 
if (process.getgid) { 


console.log('Current gid: ' + process.getgid()); 


} 


process.getegid() 
注意 : 这 个 函数 只 在 POSIX 平 台 上 有 效 (如 在 Windows，Android 中 无 效 ) ° 


获取 进程 的 有 效 群 组 标识 (参阅 getgid(2) ) 。 这 是 一 个 群 组 id 数组 ， 不 是 群 组 
名 。 


if (process.getegid) { 
console.log('Current gid: ' + process.getegid()); 


} 


process.setgid(id) 
注意 : 这 个 函数 只 在 POSIX 平 台 上 有 效 (4° Windows > Android P £32k) 。 


设置 进程 的 群 组 标识 (参阅 setgid(2) ) 。 它 接受 一 个 数字 |D 或 一 个 群 组 名 字符 
囊 。 如 果 群 组 名 被 指定 ， 那 么 这 个 方法 将 在 解析 群 组 名 为 一 个 |D 的 过 程 中 阻塞 。 


if (process.getgid && process.setgid) { 
console.log('Current gid: ' + process.getgid()); 
try 4 
process.setgid(501); 
console.log('New gid: ' + process.getgid()); 


} 


catch (err) { 
console.log('Failed to set gid: ' + err); 


process.setegid(id) 


注意 : 这 个 函数 只 在 POSIX 平 台 上 有 效 〈《 如 在 Windows，Android 中 无 效 ) 。 


RE 


置 进程 的 有 效 群 组 标识 (参阅 setgid(2) ) 。 它 接受 一 个 数字 ID 或 一 个 群 组 名 
字符 事 。 如 果 群 组 名 被 指定 ， 那 么 这 个 方法 将 在 解析 群 组 名 为 一 个 ID 的 过 程 中 阻 


o 


H 


if (process.getegid && process.setegid) { 
console.log('Current gid: ' + process.getegid()); 


try { 
process.setegid(501); 
console.log('New gid: ' + process.getegid()); 


} 


catch (err) { 
console.log('Failed to set gid: ' + err); 


process.getuid() 

注意 : 这 个 函数 只 在 POSIX 平 台 上 有 效 〈《 如 在 Windows，Android 中 无 效 ) ° 

获取 进程 的 用 户 id (参阅 getuid(2) ) 。 这 是 一 个 数字 用 户 id， 不 是 用 户 名 。 
if (process.getuid) { 


console.log('Current uid: ' + process.getuid()); 


} 


process.geteuid() 

注意 : 这 个 函数 只 在 POSIX 平 台 上 有 效 (如 在 Windows，Android 中 无 效 ) 。 
获取 进程 的 有 效用 户 id (参阅 getuid(2) ) 。 这 是 一 个 数字 用 户 id， 不 是 用 户 
Z o 


if (process.geteuid) { 
console.log('Current uid: ' + process.geteuid()); 


} 


process.setuid(id) 
注意 : 这 个 函数 只 在 POSIX 平 台 上 有 效 〈《 如 在 Windows，Android 中 无 效 ) ° 


设置 进程 的 用 户 ID (参阅 setuid(2) ) 。 它 接受 一 个 数字 ID 或 一 个 用 户 名 字符 
串 。 如 果 用 户 名 被 指定 ， 那 么 这 个 方法 将 在 解析 用 户 名 为 一 个 ID 的 过 程 中 阻塞 。 


if (process.getuid && process.setuid) { 
console.log('Current uid: ' + process.getuid()); 


ERY ft 
process.setuid(501); 


console.log('New uid: ' + process.getuid()); 


} 


catch (err) { 
console.log('Failed to set uid: ' + err); 


process.seteuid(id) 
注意 : 这 个 函数 只 在 POSIX 平 台 上 有 效 〈《 如 在 Windows，Android 中 无 效 ) ° 


设置 进程 的 有 效用 户 |D (HM seteuia(2) ) 。 它 接受 一 个 数字 |D 或 一 个 用 户 名 
符 串 。 如 果 用 户 名 被 指定 ， 那 么 这 个 方法 将 在 解析 用 户 名 为 一 个 ID 的 过 程 中 阻 


o 


Me l P 


if (process.geteuid && process.seteuid) { 
console.log('Current uid: ' + process.geteuid()); 


try { 
process.seteuid(501); 


console.log('New uid: ' + process.geteuid()); 


} 
catch (err) { 


console.log('Failed to set uid: ' + err); 


process.getgroups() 


注意 : 这 个 函数 只 在 POSIX 平 台 上 有 效 〈《 如 在 Windows，Android 中 无 效 ) 。 


fe} 


返回 一 个 补充 群 组 ID 的 数组 。 如 果 包 含 了 有 效 的 组 ID，POSIX 将 不 会 指定 
但 node.js 保证 它 始终 是 。 


process.setgroups(groups) 


注意 : 这 个 函数 只 在 POSIX 平 台 上 有 效 (40-7 Windows > Android t £24) 。 


设置 一 个 补充 群 组 ID。 这 是 一 个 特殊 的 操作 ， 意 味 着 你 需要 拥 
有 root 或 CAP_SETGID 权限 才 可 以 这 么 做 。 


列表 可 以 包含 群 组 ID， 群 组 名 ， 或 两 者 。 


process.initgroups(user, extra_group) 
注意 : 这 个 函数 只 在 POSIX 平 台 上 有 效 (如 在 Windows，Android 中 无 效 ) 。 


读 取 /etc/group 并 且 初 始 化 群 组 访问 列表 ， 使 用 用 户 是 组 员 的 所 有 群 组 。 这 是 
一 个 特殊 的 操作 ， 意 味 着 你 需要 拥有 root 或 CAP_SETGID 权限 才 可 以 这 么 做 。 


user 是 一 个 用 户 名 或 一 个 用 户 ID。 extra_group 是 一 个 群 组 名 或 群 组 ID 。 


当 你 注销 权限 时 有 些 需要 关心 的 : 


console.log(process.getgroups()); al Onl 
process.initgroups('bnoordhuis', 1000); // switch user 
console.log(process.getgroups()); M E Zur 0 4e, O00 
9 ] 

process.setgid(1000); // drop root gid 
console.log(process.getgroups()); // | 27, 30, 46, 1000 | 


[a A) 
process.version 


一 个 暴露 NODE_VERSION 的 编译 时 存储 属性 。 


console.log('Version: ' + process.version); 


process.versions 


一 个 暴露 node.js 版 本 和 它 的 依赖 的 字符 串 属 性 。 


console.log(process.versions); 


将 可 能 打印 : 


{ http parser: '2.3.0', 
node: '1.1.1', 
vaa Ast. OR TA 
UVa lO 
Abos ea. 
ares: '1.10.0-DEV', 
modules: '43', 
openssl: '1.0.1k' } 


process.config 


一 个 表示 用 于 编译 当前 node.js 执行 文件 的 配置 的 JavaScript 对 象 。 这 和 运 
行 ./configure 脚本 产生 的 config.gypi 一 样 。 


一 个 可 能 的 输出 : 


{ target_defaults: 

{ cflags: [], 
default_configuration: 'Release', 
defines: [], 
include dirs: [], 
libraries: [] }, 

variables: 

{ host_arch: 'x64', 
node_install_npm: ‘'true', 
node_prefix: '', 
node_shared_cares: 'false', 
node_shared_http_parser: 'false', 
node_shared_libuv: 'false', 
node_shared_zlib: 'false', 
node_use_dtrace: 'false', 
node_use_openssl: 'true', 
node_shared_openssl: 'false', 
strict_aliasing: ‘true’, 
target_arch: 'x64', 
v8_use_snapshot: 'true' } } 


process.kill(pid[, signal]) 


给 进程 传递 一 个 信号 。 pid 是 进程 id， signal 是 描述 信号 的 字符 串 。 信 号 码 类 
WF 'SIGINT' 或 'SIGHUP' 。 如 果 和 忽略 ， 那 么 信号 将 是 'SIGTERM' 。 更 多 信 
息 参 阅 Signal Events 和 kill(2) ° 


如 果 目 标 不 存在 将 会 抛 出 一 个 错误 ， 并 且 在 一 些 情 况 下 ，0 信号 可 以 被 用 来 测试 
进程 的 存在 。 


注意 ， 这 人 BRERAS SA Che eRe Ra 
可 能 与 杀 死 


人 
与 进程 无 关 。 


一 个 发 送信 号 给 自身 的 例子 : 


process.on('SIGHUP', function() { 
console.log('Got SIGHUP signal.'); 


}); 


setTimeout(function() { 
console. log( Exiting." ); 
process.exit(0); 

}, 100); 


process.kill(process.pid, 'SIGHUP’); 
注意 : 4 SIGUSR1 被 node.js 收 到 ， 它 会 开始 调试 。 参 阅 Signal Events ° 
process.pid# 


进程 的 PID © 


console.log('This process is pid ' + process.pid); 


process. title# 
设置 /获取 'ps' 中 显示 的 进程 名 。 


当 设 置 该 属性 时 ， 所 能 设置 的 字符 串 最 大 长 度 视 具体 平台 而 定 ， 如 果 超 过 的 话 会 自 
动 截断 。 


在 Linux f OSX 上 ， 它 受 限 于 名 称 的 字 节 长 度 加 上 命令 行 参数 的 长 度 ， 因 为 它 有 
覆盖 参数 内 存 。 


v0.8 版 本 允许 更 长 的 进程 标题 字符 串 ， 也 支持 覆盖 环境 内 存 ， 但 是 存在 潜在 的 不 安 


全 和 混乱 。 


process.arch 


返回 当前 的 处 理 器 结构 : tarm! > 'ia32' 或 'x64' © 


console.log('This processor architecture is ' + process.arch); 


process.platform 
放 回 当前 的 平 
台 : 'darwin' > 'freebsd' > '‘linux' ° 'sunos' 或 'win32' 。 


console.log('This platform is ' + process.platform); 

process.memoryUsage() 

返回 当前 node.js 进程 内 存 使 用 情况 (用 字 节 描述 ) 的 对 象 。 
var util = require('util'); 
console.log(util.inspect(process.memoryUsage())); 

可 能 的 输出 : 


{ rss: 4935680, 
heapTotal: 1826816, 
heapUsed: 650472 } 


heapTotal 和 heapUsed 指向 V8 的 内 存 使 用 。 


process.nextTick(callback[, arg][, ...]) 


e callback Function 
在 事件 循环 的 下 一 次 循环 中 调用 回调 函数 。 


这 不 是 setTimeout(fn, 0) 的 简单 别名 ， 它 更 有 效率 。 在 之 后 的 tick 中 ， 它 在 
任何 其 他 的 MO 事件 (包括 timer ) 触发 之 前 运行 。 


console.log('start'); 

process.nextTick(function() { 
console.log('nextTick callback'); 

+); 

console.log('scheduled'); 

77 OUT DUE 

// Start 

// scheduled 

// nextTick callback 


这 对 于 开发 你 想 要 给 予 用 户 在 对 象 被 构建 后 ， 任 何 l/O 发 生前 ， 去 设置 事件 监听 器 的 
机 会 时 ， 非 常 有 用 。 


function MyThing(options) { 
this.setupOptions(options); 


process.nextTick(function() { 
this.startDoingStuff(); 
}.bind(this)); 


var thing = new MyThing(); 
thing.getReadyForStuff(); 
// thing.startDoingStuff() gets called now, not before. 


这 对 于 100% 同 步 或 100% 异 步 的 API 非 常 重要 。 考 虑 一 下 例子 : 


// WARNING! DO NOT USE! BAD UNSAFE HAZARD! 
function maybeSync(arg, cb) { 
if (arg) { 
cb(); 
return; 


fS.stat( file’, cb); 


这 个 API 是 危险 的 ， 如 果 你 这 样 做 : 


maybeSync(true, function() { 
foo(); 
}); 


bar(); 
foo() 和 bar() 的 调用 次 序 是 不 确定 的 。 
更 好 的 做 法 是 : 


function definitelyAsync(arg, cb) { 


if (arg) { 
process.nextTick(cb); 
return; 


fs.stat('file', cb); 


注意 : nextTick 队列 在 每 一 次 事件 循环 的 MO 开始 前 都 要 完全 执行 完毕 。 所 以 ， 
递归 地 设置 nextTick 回调 会 阻塞 IO 的 方法 ， 就 像 一 个 while(true); 循环 。 
process.umask([mask]) 


设置 或 读 取 进程 的 文件 模式 的 创建 掩 码 。 子 进程 从 父 进程 中 继承 这 个 掩 码 。 返 回 旧 
的 掩 码 如 果 mask 参数 被 指定 。 否 则 ， 会 返回 当前 掩 码 。 


var oldmask, newmask = 0022; 


oldmask = process.umask(newmask) ; 
console.log('Changed umask from: ' + oldmask.toString(8) + 
' to ' + newmask.toString(8)); 


process.uptime() 


node. js 进程 已 执行 的 秒 数 。 


process.hrtime() 


以 [seconds, nanoseconds] 元 组 数组 的 形式 返回 高 分 辨 时 间 。 是 相对 于 过 去 的 
任意 时 间 。 它 与 日 期 无 关 所 以 不 用 考虑 时 区 等 因素 。 它 的 主要 用 途 是 衡量 程序 性 


你 可 以 将 之 前 的 process.hrtime() 返回 传递 给 一 个 新 的 process.hrtime() 来 
获得 一 个 比较 。 衡 量 性 能 时 非常 有 用 : 


var time = process.hrtime(); 
// [ 1800216, 25 ] 


setTimeout(function() { 
var diff = process.hrtime(time); 
fi New 552 | 


console.log('benchmark took %d nanoseconds', diff[0] * 1e9 + d 
Lp it); 

// benchmark took 1000000527 nanoseconds 
1, 1000); 


process.mainModule 


检索 require.main 的 备用 方式 。 区 别 是 ， 如 果 主 模块 在 运行 时 改 
变 ， require.main 可 能 仍 指向 改变 发 生前 的 被 引入 的 原 主 模块 。 通 常 ， 假 设 它 
们 一 样 是 安全 的 。 


与 require.main 一 样 ， 当 如 果 没 十 ， 它 将 是 undefined ° 
与 requi i 样 ， 当 如 果 没 有 入 口 脚 本 时 ， 它 将 是 undefined 


Process 
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punycode 


Stability: 2 - Stable 


Punycode.js 在 node.js v1.0.0+ 和 Node.js v0.6.2+ 中 被 内 置 。 通 
过 require('punycode') 来 获取 它 ( 若 要 在 其 他 版 本 的 node.js 中 使 用 它 ， 需 
要 先 通过 npm 来 安装 punycode 模块 ) 。 


punycode.decode(string) 


转换 一 个 纯 ASCII 符 号 Punycode 字符 串 为 一 个 Unicode 符号 的 字符 串 。 


decoae domain name parts 


punycode.decode('maana-pta'); // 'mafiana' 
punycode.decode('--dqo34k'); // 


punycode.encode(string) 


转换 一 个 Unicode 符号 的 字符 串 为 一 个 纯 ASCII 符 号 Punycode 字符 串 。 


// encode domain name parts 
punycode.encode('mafiana'); // 'maana-pta' 
punycode.encode('&S-%'); // '--dqo34k' 


punycode.toUnicode(domain) 

转换 一 个 代表 了 一 个 域名 的 Punycode 字符 串 为 一 个 Unicode 字符 串 。 只 有 代表 
了 域名 的 部 分 的 Punycode 字符 串 会 被 转换 。 也 就 是 说 ， 如 果 你 调用 了 一 个 已 经 被 
转换 为 Unicode 的 字符 串 ， 也 是 没有 问题 的 。 


// decode domain names 


punycode. toUnicode('xn--maana-pta.com'); // 'mafiana.com' 





punycode. toUnicode('xn----dqo34k.com'); // '&-%.com' 


punycode.toASCll(domain) 


转换 一 个 代表 了 一 个 域名 的 Unicode 字符 串 为 一 个 Unicode 字符 串 。 只 有 代表 
了 域名 的 部 分 的 非 ASCI| 字 符 串 会 被 转换 。 也 就 是 说 ， 如 果 你 调用 了 一 个 已 经 被 转 
换 为 ASCII 的 字符 串 ， 也 是 没有 问题 的 。 


// encode domain names 
punycode.toASCII('mafiana.com'); // 'xn--maana-pta.com' 
punycode.toASCII('&-#.com'); // 'xn----dqo34k.com' 


punycode.ucs2 


punycode.ucs2.decode(string) 


创建 一 个 包含 了 字符 串 中 的 每 个 Unicode 符号 的 数字 编码 点 的 数组 。 由 
于 JavaScript 在 内 部 使 用 UCS-2 ， 这 个 函数 会 将 一 对 代理 部 分 (surrogate 
halves) (UCS-2 骏 圳 的 单独 字符 ) 转换 为 一 个 单独 的 编码 点 来 匹配 UTF-16 © 


punycode.ucs2.decode('abc'); // [0x61, 0x62, 0x63] 
// surrogate pair for U+1D306 tetragram for centre: 
punycode.ucs2.decode('\uD834\uDF06'); // [0x1D306 | 


punycode.ucs2.encode(codePoints) 
基于 数字 编码 点 的 数组 ， 创 建 一 个 字符 串 。 


punycode.ucs2.encode([0x61, 0x62, 0x63]); // ‘abc' 
punycode.ucs2.encode([0x1D306]); // '\uD834\uDFO6' 


punycode.version 


一 个 代表 了 当前 Punycode.js 版 本 号 的 数字 。 


Query String 


PER: 2-28 


这 个 模块 提供 了 处 理 查询 字符 串 的 工具 。 它 提供 了 以 下 方法 : 


querystring.stringify(obj[, sep][, eq][, options]) 


BGA at BA EER o TUL TIRE RIOD (ta!) FR 
MS (tet) 。 


options 对 象 可 以 包含 encodeuRIComponent Atè (RU 
为 querystring.escape ) ， 它 被 用 来 在 需要 时 ， 将 字符 串 编码 为 非 utf-8 编 码 。 


例子 : 


querystring.stringify({ foo: 'bar', baz: ['gqux', 'quux'], corge: 
1 1 }) 

// returns 

'foo=bar&baz=qux&baz=quux&corge=' 


querystring stringify({foo: 'bar', baz: ‘qux’}, ';', '":') 
// returns 
'foo:bar;baz:qux' 


// Suppose gbkEncodeURIComponent function already exists, 

// it can encode string with ‘gbk encoding 

querystring.stringify({ w: '4 so! foo: “bar }, null, null, 
{ encodeURIComponent: gbkEncodeURIComponent }) 

// returns 

' w=%D6%D0%CE%C4&foo0=bar ' 


OE M 
querystring.parse(str[, sep][, eq][, options]) 


反 序列 化 一 个 查询 字符 囊 为 一 个 对 象 。 可 以 可 选 地 覆盖 默认 的 分 隔 符 ( 1a!) 和 
赋值 符号 ( '=! )。 


options 可 以 包含 maxkeys BE (RUA 1000 ) 。 它 被 用 来 限制 被 处 理 的 
键 。 将 其 设置 为 0 会 移 除 限制 。 


options 可 以 包含 decodeURIComponent 属性 (默认 
A querystring.unescape ) ， 它 被 用 来 在 需要 时 ， 解 码 非 uft8 编 码 字 符 串 。 


例子 : 
querystring.parse('foo=bar&baz=qux&baz=quux&corge') 


// returns 
{ foo: 'bar', baz: ['qux', 'quux'], corge: '' } 


// Suppose gbkDecodeURIComponent function already exists, 
// it can decode ‘gbk encoding string 
querystring. parse( 'w=%D6%DO%CE%C4&foo=bar', null, null, 

{ decodeURIComponent: gbkDecodeURIComponent }) 
// returns 
(ower “fsa foo: Dak! ot 


querystring.escape 


querystring.stringify 使 用 的 转 义 函数 ， 在 需要 时 可 以 被 覆盖 。 


querystring.unescape 
querystring.parse 使 用 的 反 转 义 函 数 ， 在 需要 时 可 以 被 禾 盖 。 


首先 它 会 尝试 使 用 decodeURIComponent ， 但 是 如 果 失 败 了 ， 它 就 转 而 使 用 一 个 
不 会 在 畸形 URL 上 抛 出 错误 的 更 安全 的 等 价 方法 。 


Readline 


稳定 度 :2= 狗 定 


ev 


通过 require('readline') 来 使 用 这 个 模块 。 Readline 允许 逐 行 读 取 一 个 汤 


(如 process.stdin ) ° 


注意 ， 一 旦 你 执行 了 这 个 模块 ， 你 的 node.js 程序 在 你 关闭 此 接口 之 前 ， 将 不 会 
退出 。 以 下 是 如 何 让 你 的 程序 优雅 的 退出 的 例子 : 


var readline = require('readline'); 


var rl = readline.createInterface({ 
input: process.stdin, 
output: process.stdout 


}); 


rl.question("What do you think of node.js? ", function(answer) { 
// TODO: Log the answer in a database 
console.log("Thank you for your valuable feedback:", answer); 


rl.close(); 


}); 


readline.createlnterface(options) 

创建 一 个 readline 接口 实例 。 接 受 一 个 options 对 象 ， 接 受 以 下 值 : 
e input- 需要 监听 的 可 读 流 ( 必 选 ) 。 
© output - 将 逐 行 读 取 的 数据 写 入 的 流 (可 选 ) 。 
e completer - 用 于 Tab 自 动 补 全 的 可 选 防 数 。 参 阅 下 文 的 使 用 例子 。 


e terminal - 如 果 input 和 output 流 需 要 被 像 一 个 TTY 一 样 对 待 ， 并 且 被 经 由 
ANSI/VT100 转 义 代码 写 入， 就 传递 true 。 默 认为 在 实例 化 时 ， 检 查 出 
的 ouput 流 的 isTTY 值 。 


e historySize - 保留 的 历史 记录 行 的 最 大 数量 。 默 认为 30 。 


completer 函数 被 给 予 了 一 个 用 户 和 输入 的 当前 行 ， 并 且 支 持 返 回 一 个 含有 两 个 元 
素 的 数组 : 


1. 一 个 匹配 当前 输入 补 全 的 数组 。 
2. 一 个 被 用 于 匹配 的 子 字符 串 。 
最 终 形式 如 : [[substri, substr2, ...], originalsubstring] ° 


例子 : 


function completer(line) { 

var completions = '.help .error .exit .quit .q'.split(' ') 

var hits = completions.filter(function(c) { return c.indexOf(1 
ine) == 0 }) 

// show all completions if none found 

return [hits.length ? hits : completions, line] 


completer 同样 也 可 以 以 同步 的 方式 运行 ， 如 果 它 接受 两 个 参数 : 


function completer(linePartial, callback) { 
callback(null, [['123'], linePartial]); 


createInterface 通常 与 process.stdin 和 process.stdout 搭配 ， 用 来 接 
受用 户 输 入 : 


var readline = require('readline'); 
var rl = readline.createInterface({ 
input: process.stdin, 
output: process.stdout 


+); 


一 旦 你 有 了 一 个 readline 接口 ， 你 通常 要 监听 一 个 line 事件 。 


如 果 这 个 实例 中 ， terminal A true ° AA output 流 将 会 得 到 最 好 的 兼容 
性 ， 如 果 它 定义 了 output ,columns 属性 ， 并 且 在 output 的 columns 变化 时 
( 当 它 是 一 个 TTY 时 ， process,stdout 会 自动 这 么 做 ) ， 触 发 了 一 

个 resize 事件 。 


Class: Interface 


一 个 代表 了 有 input 和 output 流 的 readline 接口 。 


rl.setPrompt(prompt) 

设置 提示 符 ， 例 如 当 你 在 命令 行 运行 iojs 命令 时 ， 你 看 到 了 > ， 这 就 
是 node.js 的 提示 符 。 

rl.prompt([preserveCursor]) 


为 用 户 的 输入 准备 好 readline ， 在 新 的 一 行 放置 当前 的 setPrompt 选项 ， 给 予 
用 户 一 个 新 的 用 于 输入 的 地 方 。 设 置 preserveCursor A true ， 来 防止 光标 位 
置 被 重 置 为 0 。 


仍 会 重 置 被 createInterface 使 用 的 input 流 ， 如 果 它 被 暂停 。 


如 果 当 调用 createInterface 时 output 被 设置 为 null 或 undefined ， 提 示 
符 将 不 会 被 写 入 
rl.question(query, callback) 


带 着 query 来 预先 放置 提示 符 ， 并 且 在 用 户 应 答 时 执行 回调 函数 。 给 用 户 展 
示 query ， 然 后 在 用 户 输入 了 应 答 后 调用 callback 。 


仍 会 重 置 被 createInterface 使 用 的 input 流 ， 如 果 它 被 暂停 。 


如 果 当 调用 createInterface 时 output 被 设置 为 null 或 undefined ， 什 么 
都 不 会 被 展示 。 


例子 : 


interface.question('wWhat is your favorite food?', function(answer 


ys 


console.log('Oh, so your favorite food is ' + answer); 


}); 
Ki! = Jo] 





rl.pause() 

暂停 readline 的 input 流 ， 人 允许 它 在 晚 些 需要 时 恢复 。 

注意 ， 带 着 事件 的 流 不 会 立刻 被 暂停 。 在 调用 了 pause 后 ， 许 多 事件 可 能 被 触 
发 ， 包 括 line 事件 。 

rl.resume() 


恢复 readline 的 input 流 。 


rl.close() 


关闭 实例 接口 ， 放 育 对 input 和 output 流 的 控制 。 close 事件 也 会 被 触发 。 


rl.write(data[, key]) 


向 output 流 写 入 数据 ， 除 非 当 调用 createInterface 时 output 被 设置 
A null 或 undefined ° key 是 一 个 代表 了 键 序列 的 对 象 ; 在 当 终 端 为 TTY 时 
可 用 。 


如 果 input 流 被 暂停 ， 它 也 会 被 恢复 。 


例子 : 


rl.write('Delete me!'); 
// Simulate ctrl+u to delete the line written previously 
rl.write(null, {ctrl: true, name: 'u'}); 


Events 


Event: ‘line’ 


e function (line) {} 


4 input 流 收 到 一 个 \n HAR? MPAA PAPOSHARR eo RE-PEA A 
户 输入 的 好 钧 子 。 


例子 : 


rl.on('line', function (cmd) { 
console.log('You just typed: '+cmd); 


}); 


Event: 'pause' 
e function () {} 
当 input 流 被 暂停 时 触发 。 


也 会 在 input 没有 被 暂停 并 且 收 到 一 个 SIGCONT 事件 时 触发 (参阅 SIGTSTP 事 
件 和 SIGCONT 事件 ) 。 


例子 : 


rl.on('pause', function() { 
console.log('Readline paused.'); 


}); 


Event: 'resume' 
e function () {} 
当 input 流 被 恢复 时 触发 。 


例子 : 


rl.on('resume', function() { 
console.log('Readline resumed.'); 


+); 


Event: ‘close’ 


e function () {} 
4 close() 被 调用 时 触发 。 


也 会 在 input 流 收 到 它 的 end 事件 时 触发 。 当 这 个 事件 触发 时 ， 接 口 实例 需要 
考虑 “被 结束 "。 例 如 ， 当 input 流 接收 到 AD (也 被 认 作 EOT ) ° 

这 个 事件 也 会 在 如 果 当 前 没有 SIGINT 事件 监听 器 ， 且 input 流 接收 到 AC (也 
被 认 作 SIGINT ) 时 触发 。 


Event: 'SIGINT' 
e function () {} 


当 input 流 接 收 到 ac (也 被 认 作 SIGINT ) 时 触发 。 如 果 当 前 没有 SIGINT # 
件 的 监听 器 ， pause 事件 将 会 被 触发 。 


例子 : 


KIRONE SIGINT A function). 4 
rl.question('Are you sure you want to exit?', function(answer) 


{ 


if (answer.match(/^y(es)?$/i)) rl.pause(); 


}); 
Pe 


E TL) 
Event: 'SIGTSTP' 
e function () {} 


在 Windows 平 台 下 不 能 使 用 。 


当 input 流 接 收 到 一 个 AZ (也 被 认 作 SIGTSTP ) 时 触发 。 如 果 当 前 没 
有 SIGTSTP 事件 的 监听 器 ， 这 个 程序 将 会 被 送 至 后 台 运 行 。 


当 程 序 使 用 fg 恢复 ， pause 和 SIGCONT 事件 都 会 被 触发 。 你 可 以 选择 其 中 的 
一 个 来 恢复 流 。 


如 果 流 在 程序 被 送 至 后 台 前 就 被 暂停 ， pause 和 SIGCONT 事件 将 不 会 触发 。 


例子 : 


EL ont SIGTSIP:; functizon() A 
// This will override SIGTSTP and prevent the program from goi 


ng to the 
// background. 
console.log('Caught SIGTSTP.'); 


}); 


Event: 'SIGCONT' 


e function () {} 
在 Windows 平 台 下 不 能 使 用 。 
当 input 流 被 AZ (也 被 认 作 SIGTSTP ) 送 至 后 台 时 触发 ， 然 后 使 用 fg(1) 继 
续 执行 。 这 个 事件 仅 在 程序 被 送 至 后 台 前 流 没有 被 暂停 时 触发 。 


例子 : 


rl.on('SIGCONT', function() { 
// prompt will automatically resume the stream 


rl.prompt(); 
}); 


Example: Tiny CLI 


下 面 是 一 个 使 用 以 上 方法 来 创建 一 个 迷你 的 控制 台 接口 的 例子 : 


var readline = require('readline'), 
rl = readline.createInterface(process.stdin, process.stdout) 


rl.setPrompt('OHAI> '); 
rl.prompt(); 


rl.on('line', function(line) { 
switch(line.trim()) { 
case 'hello': 
console.log('world!'); 
break; 
default: 
console.log('Say what? I might have heard `' + line.trim() 
yy 
break; 
} 
rl.prompt(); 
}).on('close', function() { 
console.log('Have a great day!'); 
process.exit(0); 


}); 


readline.cursorTo(stream, x, y) 


在 给 定 的 TTY 流 中 ， 将 光标 移动 到 指定 位 置 。 


readline.moveCursor(stream, dx, dy) 


在 给 定 的 TTY 流 中 ， 相 对 于 当前 位 置 ， 将 光标 移动 到 指定 位 置 。 


readline.clearLine(stream, dir) 
用 指定 的 方式 ， 在 给 定 的 TTY 流 中 ， 清 除 当 前 的 行 。 dir 可 以 是 以 下 值 之 一 : 


o -1 -从 光标 的 左边 
o 1- 从 光标 的 右边 
2 0-4 


readline.clearScreenDown(stream) 


从 当前 的 光标 位 置 ， 清 除 屏幕 。 


REPL 


稳定 度 : 2 - 稳定 


一 个 读 取 -执行 -打印 -循环 (REPL) 可 以 用 于 单独 的 程序 ， 也 能 很 容易 的 被 集成 在 
其 他 程序 中 。 REPL 提供 了 一 种 交互 着 运行 JavaScript 然后 查看 结果 的 方式 。 
它 可 以 被 用 来 调试 ， 测 试 或 只 是 尝试 一 些 东 西 。 


在 命令 行 中 不 带 任何 参数 直接 执行 iojs ， 你 会 进入 REPL 界 面 。 它 有 一 个 极 简 的 
emacs 行 编辑 器 


mjr:~$ iojs 

Type '.help' for options. 

Sawa sp 2y S 

le 

> a.forEach(function (v) { 
console.log(v); 


+); 


要 使 用 高 级 的 行 编辑 器 的 话 ， 带 着 环境 变量 NODE_NO_READLINE=1 局 
动 node.js 。 它 将 会 在 允许 你 使 用 rlwrap 的 终端 设置 中 ， 户 动 一 个 主要 的 调 
试 REPL (main and debugger REPL) 。 


例如 ， 你 可 以 把 以 下 内 容 加 入 bashrc 文件 : 


alias iojs="env NODE_NO_READLINE=1 rlwrap iojs" 


内 置 的 REPL (通过 运行 iojs 或 iojs -i BA) 可 以 被 以 下 环境 变量 所 控制 : 


NODE REDE HISTORY FEE med A E S 
文件 路 径 。 当 给 定 了 一 个 可 用 的 路 径 ， 将 启用 持久 化 的 历史 记录 支 
持 : REPL 历史 记录 将 会 跨 iojs``REPL 会 话 持久 化 。 

e NODE_REPL_HISTORY_SIZE- 默认 为 1000 ° 


与 NODE_REPL_HISTORY_FILE 结合 ， 控 制 需要 持久 化 的 历史 记录 数量 。 必 须 
为 正 数 。 

e NODE REPL MODE -可 以 是 sloppy ， strict 或 magic 中 的 一 个 。 默 
认为 magic ， 会 自动 在 严格 模式 中 执行 "strict mode only" 声明 。 


repl.start(options) 


返回 并 启动 一 个 REPLServer 实例 ， 继 承 于 [Readline Interface][] ° #x— 
个 包含 以 下 值得 options HR: 


e prompt- 所 有 1/0 的 提示 符 。 默 认为 > © 
e input- 监听 的 可 读 流 。 上 默认 为 process.stdin ° 
e output - 输出 数据 的 可 写 流 。 默 认为 process.stdout ° 


e terminal - 如 果 流 需要 被 像 TTY 对 待 ， 并 且 有 ANSI/VT100 转 义 代码 写 入 ， 设 
置 其 为 true 。 默 认为 在 实例 化 时 检查 到 的 output 流 的 isTTY 属性 。 


o eval - 被 用 来 执行 每 一 行 的 函数 。 默 认为 被 异步 包装 过 的 eval() 。 参 阅 下 文 
的 自 定义 eval 的 例子 。 


e USeColors - 一 个 表明 了 是 否 writer 函数 需要 输出 颜色 的 布尔 值 。 如 果 设 置 
了 不 同 的 writer 函数 ， 那 么 它 什么 都 不 会 做 。 默 认为 REPL 的 终端 值 。 


e useGlobal- 若 设置 为 true ， 那 么 REPL 将 使 用 全 局 对 象 ， 而 不 是 运行 每 一 
个 脚本 在 不 同上 下 文中 。 默 认为 false 。 


e ignoreUndefined - 若 设 置 为 true ， 那 么 如 果 返 回 值 
是 undefined ， REPL 将 不 会 输出 它 。 默 认为 false 。 


e writer - 当 每 一 个 命令 被 执行 完毕 时 ， 都 会 调用 这 个 函数 ， 它 返回 了 展示 的 格式 
(包括 颜色 ) 。 默 认为 util.inspect ° 


e replMode - 控制 是 否 REPL 运行 所 有 的 模式 在 严格 模式 ， 默 认 模 式 ， 或 混合 
模式 〈 "magic" 模式 ) 。 接 受 以 下 值 : 


o repl.REPL_MODE_SLOPPY - 在 混杂 模式 下 运行 命 

o repl.REPL _MODE_STRICT - 在 严格 模式 下 运行 命令 。 这 与 在 每 个 命令 前 
添加 ‘use strict' 语句 相等 。 

o repl.REPL_MODE_MAGIC - 试图 在 默认 模式 中 运行 命令 ， 如 果 失 败 了 ， 
会 重新 尝试 使 用 严格 模式 。 


你 可 以 使 用 你 自己 的 eval 函数 ， 如 果 它 包含 以 下 签名 : 


function eval(cmd, context, filename, callback) { 
callback(null, result); 


在 用 tab 补 全 时 - eval 将 会 带 着 一 个 作为 输入 字符 串 的 ,scope 调用 。 它 被 期 望 
返回 一 个 scope 名 字数 组 ， 被 用 来 自动 补 全 。 

多 个 REPL 可 以 运行 相同 的 node.js 实例 。 共 享 同 一 个 全 局 对 象 ， 但 是 各 自 的 IO 
独立 。 


下 面 是 在 stdin ，Unix socket 和 TCP socket 上 启动 一 个 REPL 的 例子 : 


var net = require("net"), 
repli = reduire (repliki 


connections = 0; 


repl.start({ 
prompt: "node.js via stdin> ", 
input: process.stdin, 
output: process.stdout 


}); 


net.createServer(function (socket) { 

connections += 1; 

repl.start({ 
prompt: "node.js via Unix socket> ", 
input: socket, 
output: socket 

+) on( exit', function() { 
socket.end(); 


}) 
}).listen("/tmp/iojs-repl-sock"); 


net.createServer(function (socket) { 

connections += 1; 

repl.start({ 
prompt: "node.js via TCP socket> ", 
input: socket, 
output: socket 

Fon( ‘exit’, function( ) 4 
socket.end(); 


}); 
}).listen(5001); 


在 命令 行 中 运行 这 个 程序 会 在 stdin 上 启动 一 个 REPL 。 另 外 的 REPL 客户 端 将 
会 通过 Unix socket 或 TCP socket 连接 。 telnet 在 连接 TCP socket 时 非 
常 有 用 ， socat 在 连接 Unix socket 和 TCP socket 时 都 非常 有 用 。 


通过 从 基于 Unix socket 的 服务 器 启动 REPL ， 你 可 以 不 用 重启 ， 而 连接 到 一 个 
长 久 执 行 的 (long-running) node.js 进程 。 


一 个 通过 net.Server 和 net.Socket 实例 运行 “全 特性 ”( 终 端 ) REPL 的 例 
子 ， 参 阅 https://gist.github.com/2209310 ° 


一 个 通过 curl(1) 运行 REPL 的 例子 ， 参 
阅 https://gist.github.com/2053342 ° 


Event: ‘exit’ 


e function () {} 


当 用 户 通过 任意 一 种 已 定义 的 方式 退出 REPL 时 触发 。 具 体 地 说 ， 在 REPL 中 键 
A ,exit ， 两 次 按 下 Ctrl+C 来 发 送 SIGINT 信号 ， 按 下 Ctrl+D 来 发 送 结 


r.on('exit', function () { 
console.log('Got "exit" event from repl!'); 
process.exit(); 


}); 


Event: 'reset' 


e function (context) {} 


当 REPL 内 容 被 重 置 时 触发 。 当 你 键入 .clear 时 发 生 。 如 果 你 以 { useGlobal: 
true } BA REPL ， 那 么 这 个 事件 将 永远 不 会 触发 。 


例子 : 


// Extend the initial repl context. 
r = repl.start({ options ... }); 
someExtension.extend(r.context); 


// When a new context is created extend it as well. 

r.on('reset', function (context) { 
console.log('repl has a new context'); 
someExtension.extend(context); 


}); 


REPL 特性 
在 REPL 内 ， 按 下 Control+D 将 会 退出 。 多 行 表 达 式 可 以 被 输入 。Tab 补 全 同时 
支持 全 局 和 本 地 变量 。 


核心 模块 将 会 被 按 需 载 入 环境 。 例 如 ， 调 用 fs ， 将 会 从 global.fs 获取 ， 作 
为 require() fs 模块 的 替代 。 


特殊 的 变量 _ (PRIA) 包含 了 上 一 个 表达 式 的 结果 。 


[ van, wpis We ] 
cat, ‘bey Gu ] 


REPL 可 以 访问 全 局 作用 域 里 的 任何 变量 。 你 可 以 通过 将 变量 赋值 给 一 个 关联 了 所 
有 REPLServer 的 context 对 象 来 暴露 一 个 对 象 给 REPL 。 例 子 : 


pl_test.js 
var repl = require("repl"), 
msg = "message"; 


repl.start("> ").context.m = msg; 


context 对 象 里 的 对 象 会 表现 得 像 REPL 的 本 地 变量 : 


mjr:~$ iojs repl_test.js 
>m 
'message' 


以 下 是 一 些 特殊 的 REPL 命令 : 


e break- 当 你 输入 一 个 多 行 表 达 式 时 ， 有 时 你 走神 了 ， 或 有 时 你 不 关心 如 何 完 
成 它 了 。 ,break 将 会 让 你 重新 来 过 。 

e clear- 重 置 context 对 象 为 一 个 空 对 象 并 且 清 除 所 有 多 行 表 达 式 。 

e exit- 关闭 MO 流 ， 意 味 着 会 导致 REPL 退出 。 


e help- 展示 特殊 命令 列表 。 
e ,Save 将 当前 的 REPL 会 话 保存 入 一 个 文件 。 


o .save ./file/to/save.js 
e .load - 从 一 个 文件 中 加 载 REPL 会 话 。 


o .load ./file/to/load.js 
这 些 组 合 键 在 REPL 中 有 以 下 影响 : 


e ctrl+C-4 ,break 关键 字 相 似 。 终 止 当 前 命 
制 退 出 。 

e ctrl+D- 与 ,exit 关键 字 相 似 。 

e tab- 展示 所 有 的 全 局 和 本 地 变量 。 


> 


Stream 


稳定 度 : 2 -稳定 


流 是 一 个 被 node.js 内 部 的 许多 对 象 所 实现 的 抽象 接口 。 例 如 一 个 发 往 HTTP 服 
务 器 的 请 求 是 一 个 留 ， stdout 也 是 一 个 流 。 流 可 以 是 可 读 的 ， 可 写 的 或 双向 的 。 
所 有 的 流 都 是 EventEmitter 实例 。 

你 可 以 通过 require('stream') 来 取 货 Stream 的 基 类 。 其 中 包括 

了 Readable 流 ，Writable 流 ， Duplex 流 和 Transform 流 的 基 类 。 


此 文档 分 为 三 个 章节 。 第 一 章节 解释 了 在 你 的 编程 中 使 用 流 时 需要 的 API。 如 果 你 
不 需要 实现 你 自己 的 流 式 API， 你 可 以 在 这 里 停止 。 


第 二 章节 解释 了 你 在 构建 你 自己 的 流 时 需要 的 API， 这 些 API 是 为 了 方便 你 这 么 做 而 
设计 的 。 


第 三 章节 深入 讲述 了 流 的 工作 机 制 ， 包 括 一 些 内 部 的 机 制 和 函数 ， 你 不 应 该 去 改动 
它 A 


们 除非 你 知道 你 在 做 什么 


面向 流 消 费 者 的 API 
流 可 以 是 可 读 的 ， 可 写 的 ， 或 双 工 的 。 


所 有 的 流 都 是 EventEmitters 。 但 是 它们 也 各 自 有 一 些 独 特 的 方法 和 属性 ， 这 取 
决 于 它们 是 可 读 流 ? 可 写 流 或 双 工 流 9 


chen anal 写 的 ， 那 么 表示 它 实 现 了 以 下 所 有 的 方法 和 事件 。 所 
这 些 AP| 同 时 也 涵盖 Duplex 或 Transform 流 ， 即 使 它们 的 实现 可 能 有 些 不 

Iq 

在 你 程序 中 ， 为 了 消费 流 而 去 实现 流 接 口 不 是 必须 的 。 如 果 你 确实 正在 你 的 程序 中 

实现 流 接 口 ， 请 参考 下 一 章节 面向 流 实现 者 的 API 。 

几乎 所 有 node.js 程序 ， 不 论 多 简单 ， 都 使 用 了 流 。 下 面 是 一 个 在 node.js 是 

使 用 流 的 例子 : 


var http = require('http'); 


Stream 


var server = http.createServer(function (req, res) { 
// req is an http.IncomingMessage, which is a Readable Stream 
// res is an http.ServerResponse, which is a Writable Stream 


var body = ''; 
// we want to get the data as utf8 strings 
// If you don't set an encoding, then you'll get Buffer objects 


req.setEncoding('utf8'); 


// Readable streams emit 'data' events once a listener is added 


req.on('data', function (chunk) { 
body += chunk; 
+); 


// the end event tells you that you have entire body 
req.on('end', function () { 
Enyi 
var data = JSON.parse(body); 
} catch (er) { 
// uh oh! bad json! 
res.statusCode = 400; 
return res.end('error: ' + er.message); 


// write back something interesting to the user: 
res.write(typeof data); 
res.end(); 
+); 
}); 


server.listen(1337); 


Ji S Cur ocalnost: 1327 =e p 

// object 

fi SS CURL LOCdI NOSE loot dn OO. 

// string 

We Secure tocalhost.is37 dm Noe) Son 


256 


// error: Unexpected token o 


a] 








Class: stream.Readable 


可 读 流 接口 是 一 个 你 可 以 从 之 读 取 数据 的 数据 源 的 抽象 。 换 句 话 说， 数据 从 可 读 流 


除非 你 指示 已 经 准备 好 接受 数据 ， 否 则 可 读 流 不 会 开始 发 生 数 据 。 


可 读 流 有 两 个 "模式 ”: 流动 模式 和 暂停 模式 。 当 在 流动 模式 时 ， 数 据 由 底层 系统 读 
出 ， 并 且 会 尽快 地 提供 给 你 的 程序 。 当 在 暂停 模式 时 ， 你 必须 调 
用 stream.read() 方法 来 获取 数据 块 。 流 默认 是 暂停 模式 。 


注意 : 如 果 data 事件 没有 被 绑 定 监听 器 ， 并 且 没 有 导 流 (pipe) 目标 ， 并 且 流 被 
切换 到 了 流动 模式 ， 那 么 数据 将 会 被 丢失 。 


你 可 以 通过 下 面 任意 一 个 做 法 切换 到 流动 模式 : 
e 添加 一 个 data 事件 的 监听 器 来 监听 数据 。 
e 调用 resume() 方法 来 明确 开启 流动 模式 。 
e 调用 pipe() 方法 将 数据 导入 一 个 可 写 流 。 
你 可 以 同意 下 面 任意 一 种 方法 切换 回 暂停 模式 : 
eo 如 果 没 有 导 流 (pipe) 目标 ， 调 用 pause() 方法 。 


e WRA Tit (pipe) 目标 ， 移 除 所 有 的 data 事件 监听 器 ， 并 且 通 
过 unpipe() 方法 移 除 所 有 导 流 目标 。 


注意 ， 由 于 为 了 向 后 兼任 的 原因 ， 移 除 data 事件 的 监听 器 将 不 会 自动 暂停 流 。 同 
样 的 ， 如 果 有 导 流 目标 ， 调 用 pause() 方法 将 不 会 保证 目标 流 排 空 并 请 求 更 多 数 
据 时 保持 暂停 。 
一 些 内 置 的 可 读 流 例 子 : 

。 客户 端的 HTTP 请 求 

o 服务 端的 HTTP 响 应 

。 文件 系统 读 取 流 


e zlib 流 


e crypto 流 


e tcp sockets 
e 子 进程 的 stdout 和 stderr 
e process.stdin 
Event: 'readable' 
当 一 个 数据 块 能 可 以 从 流 中 被 读 出 时 ， 会 触发 一 个 readable 事件 。 


些 情 况 下 ， 监 听 一 个 readable 事件 会 导致 一 些 将 要 被 读 出 的 数据 从 底层 系统 进 
内 部 缓冲 ， 如 果 它 没有 准备 好 。 


某 
入 


var readable = getReadableStreamSomehow( ); 
readable.on('readable', function() { 
// there is some data to read now 


}); 


4 ASR RAE > A ERMES readable 事件 会 再 次 触发 。 


Event: 'data' 
e chunk Buffer | String 数据 块 


为 一 个 没有 被 暂停 的 流 添 加 一 个 data 事件 的 监听 器 会 使 其 切换 到 流动 模式 。 之 后 
数据 会 被 尽快 得 传递 给 用 户 。 


如 果 你 只 是 想 尽快 得 从 流 中 取得 所 有 数据 ， 这 是 最 好 的 方式 。 
var readable = getReadableStreamSomehow( ); 
readable.on('data', function(chunk) { 


console.log('got %d bytes of data', chunk.length); 
+); 


Event: ‘end’ 
当 没 有 更 多 可 读 的 数据 时 这 个 事件 会 被 触发 。 


注意 ， 除 非 数 据 被 完全 消费 ， end 事件 才 会 触发 。 过 切换 到 流动 模式 ， 
或 重复 调用 read() 方法 。 


var readable = getReadableStreamSomehow( ); 
readable.on('data', function(chunk) { 

console.log('got %d bytes of data', chunk.length); 
}); 


readable.on('end', function() { 
console.log('there will be no more data.'); 


}); 


Event: ‘close’ 
当 底 层 资源 (如 源头 的 文件 描述 符 ) 被 关闭 时 触发 。 不 是 所 有 的 流 都 会 触发 这 个 事 
件 。 
Event: ‘error’ 
e Error Object 


当 接 受 数 据 时 有 错误 发 生 ， 会 触发 此 事件 。 


readable.read([size]) 


e size Number 可 选 ， 指 定 读 取 数 据 的 数量 
e Return String | Buffer | null 


read() 方法 从 内 部 缓冲 中 取出 数据 并 返回 它 。 如 果 没 有 可 用 数据 ， 那 么 将 返 
= null 。 


如 果 你 传递 了 一 个 size 参数 ， 那 么 它 将 返回 指定 字 节 的 数据 。 如 果 size 参数 
的 字 节 数 不 可 用 ， 那 么 将 返回 null 。 


如 果 你 不 指定 size 参数 ， 那 么 将 会 返回 内 部 缓冲 中 的 所 有 数据 。 


这 个 方法 只 能 在 暂 定 模式 中 被 调用 。 在 流动 模式 下 ， 这 个 方法 会 被 自动 地 重复 调 
用 ， 知 道内 部 缓冲 被 排 室 。 


var readable = getReadableStreamSomehow( ); 
readable.on('readable', function() { 
var chunk; 
while (null !== (chunk = readable.read())) { 
console.log('got %d bytes of data', chunk.length); 
} 
}); 


如 果 这 个 方法 返回 一 个 数据 块 ， 那 么 它 也 会 触发 data 事件 。 


readable.setEncoding(encoding) 


e encoding String 使 用 的 编码 
e Return: this 


调用 这 个 函数 会 导致 流 返 回 指定 编码 的 字符 串 而 不 是 Buffer WHR o Hite > to RAK 

调用 readable.setEncoding('utf8') ， 那 么 输出 的 数据 将 被 解释 为 UTF-8 数 

据 ， 并 且 作 为 字符 串 返 回 。 如 果 你 调用 了 readable.setEncoding('hex') > # 
么 数据 将 被 使 用 十 六 进 制 字符 串 的 格式 编码 。 


该 方法 可 以 正确 地 处 理 多 字 节 字符 。 如 果 你 只 是 简单 地 直接 取出 缓冲 并 且 对 它们 调 
用 buf.toString(encoding) ， 将 会 导致 错位 。 如 果 你 想 使 用 字符 串 读 取 数据 ， 
请 使 用 这 个 方法 。 


var readable = getReadableStreamSomehow( ); 
readable.setEncoding('utf8'); 
readable.on('data', function(chunk) { 

assert.equal(typeof chunk, 'string'); 

console.log('got %d characters of string data', chunk.length); 


}); 


readable.resume() 


e Return: this 


这 个 方法 将 会 让 可 读 流 继续 触发 data 事件 。 


这 个 方法 将 会 使 流 切 换 至 流动 模式 。 如 果 你 不 想 消费 流 中 的 数据 ， 但 你 想 监 听 它 
的 end 事件 ， 你 可 以 通过 调用 readable.resume() 来 打开 数据 流 。 


var readable = getReadableStreamSomehow( ); 
readable.resume(); 


readable.on('end', function() { 


console.log('got to the end, but did not read anything'); 
+); 


readable.pause() 


e Return: this 


这 个 方法 会 使 一 个 处 于 流动 模式 的 流 停止 触发 data 事件 ， 并 切换 至 暂停 模式 。 所 
有 可 用 的 数据 将 仍然 存在 于 内 部 缓冲 中 。 


var readable = getReadableStreamSomehow( ) ， 
readable.on('data', function(chunk) { 
console.log('got %d bytes of data', chunk.length); 
readable.pause(); 
console.log('there will be no more data for 1 second'); 
setTimeout(function() { 


console.log('now data will start flowing again'); 
readable.resume(); 


+, 1000); 
+); 


readable.isPaused() 
e Return: Boolean 


这 个 方法 会 返回 流 是 否 被 客户 端 代 码 所 暂停 (调用 readable.pause() ， 并 且 没 
有 在 之 后 调用 readable.resume() ) ° 


var readable = new stream.Readable 


readable.isPaused() // === false 
readable. pause( ) 
readable.isPaused() // === true 
readable. resume() 
readable.isPaused() // === false 


readable.pipe(destination[, options]) 


e destination Writable Stream 写 入 数据 的 目标 
e options Object 
o end Boolean 当 读 取 者 结束 时 结束 写 入 者 。 默 认为 true ° 


这 个 方法 会 取出 可 读 流 中 所 有 的 数据 ， 并 且 将 之 写 入 指定 的 目标 。 这 个 方法 会 自动 


调节 流量 ， 所 以 当 快 速 读 取 可 读 流 时 目标 不 会 溢出 。 
可 以 将 数据 安全 地 寻 流 至 多 个 目标 。 
var readable = getReadableStreamSomehow( ); 
var writable = fs.createWriteStream('file.txt'); 


// All the data from readable goes into ‘'file.txt' 


readable.pipe(writable); 


这 个 函数 返回 目标 流 ， 所 以 你 可 以 链 式 调用 pipe() 


var r = fs.createReadStream('file.txt'); 

var Z = zlib.createGzip(); 

var w = fs.createwWriteStream('file.txt.gz'); 
r.pipe(z).pipe(w) ; 


例子 ， 模 仿 UNIX 的 cat 命令 : 


process.stdin.pipe(process.stdout); 


默认 情况 下 ， 当 源流 触发 end 事件 时 ， 目 标 流 会 被 调用 end() 方法 ， 然 后 目标 
就 不 再 是 可 写 的 了 。 将 传递 { end: false } 作为 options 参数 ， 将 保持 目标 流 
开启 。 


例子 ， 保 持 被 写 入 的 流 开 启 ， 所 以 “Goodbye” 可 以 在 末端 被 写 入 : 


reader.pipe(writer, { end: false }); 
reader.on('end', function() { 
writer.end( 'Goodbye\n' ); 


注意 ， 不 论 指定 任何 options #2 > process.stderr 和 process.stdout 在 
出 前 永远 不 会 被 关闭 。 


readable.unpipe([destination]) 

e destination Writable Stream 可 选 ， 指 定 解除 导 流 的 流 
这 方法 会 移 除 之 前 调用 pipe() 方法 所 设置 的 钧 子 。 
如 果 没 有 指定 目标 ， 那 么 所 有 的 导 流 都 会 被 移 除 。 


如 果 指 定 了 目标 ， 但 是 并 没有 为 目标 设置 导 流 ， 那 么 什么 都 不 会 发 生 。 


var readable = getReadableStreamSomehow( ); 

var writable = fs.createWriteStream('file.txt'); 

// All the data from readable goes into 'file.txt', 

// but only for the first second 

readable.pipe(writable); 

setTimeout(function() { 
console.log('stop writing to file.txt'); 
readable.unpipe(writable); 
console.log('manually close the file stream'); 
writable.end(); 

P1000): 


readable.unshift(chunk) 


e chunk Buffer | String 要 插 回 读 取 队 列 开 头 的 数据 块 。 


该 方法 在 许多 场景 中 都 很 有 用 ， 比 如 一 个 流 正在 被 一 个 解析 器 消费 ， 解 析 器 可 能 需 
要 将 茶 些 刚 拉 取出 的 数据 “ 逆 消费 "回来 源 ， 以 便 流 能 将 它 传递 给 其 它 消费 者 。 


如 果 你 发 现 你 必须 经 常 在 你 的 程序 中 调用 stream.unshift(chunk) ， 你 应 该 考虑 
实现 一 个 Transform À (参阅 下 文 的 面向 流 实 现 者 的 API) © 


// Pull off a header delimited by \n\n 
// use unshift() if we get too much 
// Call the callback with (error, header, stream) 
var StringDecoder = require('string_decoder').StringDecoder ; 
function parseHeader(stream, callback) { 
stream.on('error', callback); 
stream.on('readable', onReadable); 
var decoder = new StringDecoder('utf8'); 
var header = ''; 
function onReadable() { 
var chunk; 
while (null !== (chunk = stream.read())) { 
var str = decoder.write(chunk); 
if (str.match(/\n\n/)) { 
// found the header boundary 
var split = str.split(/\n\n/); 
header += split.shift(); 
var remaining = split.join('\n\n'); 
var buf = new Buffer(remaining, 'utf8'); 
if (buf.length) 
stream.unshift (buf); 
stream.removeListener('error', callback); 
stream.removeListener('readable', onReadable); 
// now the body of the message can be read from the stre 
am. 
callback(null, header, stream); 
} else { 
// still reading the header. 
header += str; 


readable.wrap(stream) 
e stream Stream 一 个 “日 式 ” 可 读 流 


Node.js v0.10 以 及 之 前 版 本 的 流 没 有 完全 包含 如 今 的 所 有 的 流 API (更 多 的 信 
息 请 参阅 下 文 的 “兼容 性 ") o 


如 果 你 正在 使 用 一 个 老 旧 的 node.js 库 ， 它 触发 data 时 间 并 且 有 一 个 仅 作 查 询 
用 途 的 pause() 方法 ， 那 么 你 可 以 调用 wrap() 方法 来 创建 一 个 使 用 “旧式 ” 流 作 
为 数据 源 的 可 读 流 。 


你 几乎 不 会 用 到 这 个 函数 ， 它 的 存在 仅 是 为 了 老 昌 的 node.js 程序 和 库 交 互 。 
例子 : 

var OldReader = require('./old-api-module.js').OldReader; 

var oreader = new OldReader; 


var Readable = require('stream').Readable; 
var myReader = new Readable().wrap(oreader ); 


myReader.on('readable', function() { 
myReader.read(); // etc. 


}); 


Class: stream.Writable 
可 写 流 接口 是 一 个 你 可 以 向 其 写 入 数据 的 目标 的 抽象 。 


一 些 内 部 的 可 写 流 例子 : 


客户 端的 http 请 求 
e 服务 端的 http 响 应 
e 文件 系统 写 入 流 
e zlib 流 

e crypto 流 

e tcp socket 

e 子 进 程 stdin 


e process.stdout ， process.stderr 


writable.write(chunk[, encoding][, callback) 


e chunk String | Buffer 要 写 入 的 数据 

e encoding String 编码 ， 如 果 数 据 块 是 字符 串 

e callback Function 当 数 据 块 写 入 完毕 后 调用 的 回调 函数 
e Returns: Boolean 如 果 被 全 部 处 理 则 返回 true 


该 方法 向 底层 系统 写 入 数据 ， 并 且 当 数据 被 全 部 处 理 后 调用 指定 的 回调 函数 。 


返回 值 指示 了 你 是 否 可 以 立刻 写 入 数据 。 如 果 数 据 需 要 被 内 部 缓冲 ， 会 返 

E false ° GMA true 。 

返回 值 经 供 参 考 。 即 使 返回 false ， 你 仍 可 以 继续 写 入 数据 。 但 是 ， 写 入 的 数据 
将 会 被 缓冲 在 内 存 里 ， 所 以 最 好 不 要 这 样 做 。 应 该 在 写 入 更 多 数据 前 等 

待 drain 事件 。 


Event: ‘drain’ 


如 果 一 个 writable.write(chunk) 调用 返回 了 false ， 那 么 drain 事件 会 指 
示 出 可 以 继续 向 流 写 入 数据 的 时 机 “。 


// Write the data to the supplied writable stream 1MM times. 
// Be attentive to back-pressure. 
function writeOneMillionTimes(writer, data, encoding, callback) 
{ 
var 1 = 1000000; 
write(); 
function write() { 
var ok = true; 
do { 
i -=1; 
if (i === 0) { 
// last time! 
writer.write(data, encoding, callback); 
} else { 
// see if we should continue, or wait 
// don't pass the callback, because we're not done yet. 
ok = writer.write(data, encoding); 
} 
} while (i > © && ok); 
af (S oN i 
// had to stop early! 
// write some more once it drains 
writer.once('drain', write); 


writable.cork() 
强制 滞留 所 有 写 入 。 


滞留 的 数据 会 在 调用 .uncork() 或 .end() 方法 后 被 写 入 。 


writable.uncork() 


写 入 在 调用 .cork() AKA A Di A A BE © 


writable.setDefaultEncoding(encoding) 


e encoding String 新 的 默认 编码 


设置 一 个 可 写 流 的 默认 编码 。 


writable.end([chunk][, encoding][, callback]) 


e chunk String | Buffer 可 选 ， 写 入 的 数据 
e encoding String 编码 ， 如 果 数 据 块 是 字符 串 
e callback Function "T 2% > © % žr 


XAA ESTEA > AAAS o aR T EAA o” MASRAM 
A finish 事件 的 监听 器 。 
在 调用 了 end() 后 调用 write() 会 导致 一 个 错误 。 


// write 'hello, ' and then end with ‘'world!' 
var file = fs.createwriteStream('example.txt'); 
file.write('hello, '); 


file.end('world!'); 
// writing more now is not allowed! 


Event: ‘finish’ 
当 调用 了 end() 方法 ， 并 且 所 有 的 数据 都 被 写 入 了 底层 系统 ， 这 个 事件 会 被 甬 
发 o 


var writer = getWritableStreamSomehow( ); 

fon (Vay 1 ="); 1 = 100; rt f 
writer.write('hello, #' + i + '!\n'); 

} 

writer.end('this is the end\n'); 

writer.on('finish', function() { 
console.error('all writes are now complete.'); 


}); 


Event: 'pipe' 


e src Readable Stream 对 这 个 可 写 流 进行 导 流 的 源 可 读 流 


这 个 事件 将 会 在 可 读 流 被 一 个 可 写 流 使 用 pipe() 方法 进行 导 流 时 触发 。 


var writer = getWritableStreamSomehow( ); 

var reader = getReadableStreamSomehow( ); 

writer.on('pipe', function(src) { 
console.error('something is piping into the writer'); 
assert.equal(src, reader); 


}); 


reader.pipe(writer); 


Event: ‘unpipe' 
e src Readable Stream 对 这 个 可 写 流 停止 导 流 的 源 可 读 流 
当 可 读 流 对 其 调用 unpipe() 方法 ， 在 源 可 读 流 的 目标 集合 中 删除 这 个 可 写 流 ， 这 


个 事件 将 会 触发 。 


var writer = getWritableStreamSomehow( ); 

var reader = getReadableStreamSomehow( ); 

writer.on('unpipe', function(src) { 
console.error('something has stopped piping into the writer'); 
assert.equal(src, reader); 


H); 
reader.pipe(writer); 
reader.unpipe(writer ); 


Event: ‘error’ 


e Error object 


在 写 入 数据 或 导 流 发 生 错误 时 触发 。 


Class: stream.Duplex 
双 工 是 同时 实现 了 可 读 流 与 可 号 流 的 借口 。 它 的 用 处 请 参阅 下 文 。 
内 部 双 工 流 的 例子 : 


e tcp socket 


e zlib 流 


e crypto Ñ 


Class: stream.Transform 


转换 流 是 一 种 输出 由 输入 计算 所 得 的 栓 共 流 。 它 们 同时 集成 了 可 读 流 与 可 写 流 的 借 
口 。 它 们 的 用 处 请 参阅 下 文 。 


内 部 转换 流 的 例子 : 


e zlib 流 


e crypto Ñ 


面向 流 实 现 者 的 API 
实现 所 有 种 类 的 流 的 模式 都 是 一 样 的 : 


1. 为 你 的 子 类 继承 合适 的 父 类 ( util,inherits 非常 合适 于 做 这 个 ) © 

2. 为 了 保证 内 部 机 制 被 正确 初始 化 ， 在 你 的 构造 函数 中 调用 合适 的 父 类 构造 函 
数 。 

3. 实现 一 个 或 多 个 特定 的 方法 ， 参 阅 下 文 。 


被 扩展 的 类 和 要 实现 的 方法 取决 于 你 要 编写 的 流 类 的 类 型 : 


用 途 类 需要 实现 的 方法 

只 读 Readable _read 
只 写 Writable _write, _writev 
TRATE Duplex _read, _write, _writev 
操作 被 写 入 数据 ， 然 后 读 出 结果 Transform _transform，flush 


在 你 的 实现 代码 中 ， 非 常 重要 的 一 点 是 永远 不 要 调用 上 文 的 面向 流 消 费 者 的 API。 
否则 ， 你 在 程序 中 消费 你 的 流 接 口 时 可 能 有 潜在 的 副作用 。 


Class: stream.Readable 


stream.Readable 是 一 个 被 设计 为 需要 实现 底层 的 _read(size) 方法 的 抽象 
类 。 


请 参阅 上 文 的 面向 流 消费 者 的 API 来 了 解 如 何在 程序 中 消费 流 。 以 下 解释 了 如 果 在 
你 的 程序 中 实现 可 读 流 。 


例子 : 一 个 计数 流 


这 是 一 个 可 读 流 的 基础 例子 。 它 从 1 到 1，000，000 递 增 数字 ， 然 后 结束 。 


var Readable = require('stream').Readable; 
var util = require('util'); 
util.inherits(Counter, Readable); 


function Counter(opt) { 
Readable.call(this, opt); 
this._max = 1000000; 
this._index = 1; 


Counter.prototype._ read = function() { 
var i = this. index++; 
if (i > this._max) 
this.push(null); 
else { 
var str = '' + i; 
var buf = new Buffer(str, ‘ascii'); 
this.push(buf); 
} 
}; 


例子 : 简单 协议 v1 (次 优 ) 


这 类 似 于 上 文中 提 到 的 parseHeader 有 函数 ， 但 是 使 用 一 个 自 定 义 流 实现 。 另 外 ， 
注意 这 个 实现 不 将 流入 的 数据 转换 为 字符 串 。 


更 好 地 实现 是 作为 一 个 转换 流 实现 ， 请 参阅 下 文 更 好 地 实现 。 


// A parser for a simple data protocol. 

// The "header" is a JSON object, followed by 2 \n characters, a 
nd 

// then a message body. 

is 


stream 


// NOTE: This can be done more simply as a Transform stream! 


// Using Readable directly for this is sub-optimal. See the 


// alternative example below under the Transform section. 


var Readable = require('stream').Readable; 
var util = require('util'); 


util.inherits(SimpleProtocol, Readable); 


function SimpleProtocol(source, options) { 
if (!(this instanceof SimpleProtocol) ) 
return new SimpleProtocol(source, options); 


Readable.call(this, options); 
this._inBody = false; 
this._sawFirstCr = false; 


// source is a readable stream, such as a socket or file 
this._source = source; 


var self = this; 

source.on('end', function() { 
self.push(null); 

}); 


// give it a kick whenever the source is readable 
// read(0) will not consume any bytes 
source.on('readable', function() { 

self.read(0); 


}); 
this._rawHeader = []; 


this.header = null; 


SimpleProtocol.prototype._read = function(n) { 
if (!this._inBody) { 
var chunk = this._source.read(); 


// if the source doesn't have data, we don't have data 


yerr 


NO 


NO 


if (chunk === null) 
return this.push(''); 


// check if the chunk has a \n\n 


var split = -1; 
for (var i = 0; i < chunk.length; i++) { 
if (chunk[i] === 10) { // '\n' 
if (this._sawFirstcCr) { 
split = i; 
break; 
} else { 
this._sawFirstCr = true; 
} 
} else { 
this._sawFirstCr = false; 
} 
} 
if (split === -1) { 


// still waiting for the \n\n 
// stash the chunk, and try again. 
this._rawHeader.push(chunk); 
this.push(''); 
} else { 
this._inBody = true; 
var h = chunk.slice(0, split); 
this._rawHeader.push(h); 
var header = Buffer.concat(this._rawHeader).toString(); 
try { 
this.header = JSON.parse(header); 
} catch (er) { 
this.emit('error', new Error('invalid simple protocol da 
ta')); 
return; 
} 
// now, because we got some extra data, unshift the rest 
// back into the read queue so that our consumer will see 
Er 
var b = chunk.slice(split); 
this.unshift(b); 


// and let them know that we are done parsing the header. 
this.emit('header', this.header); 


} 
} else { 


// from there on, just provide the data to our consumer. 
// careful not to push(null), since that would indicate EOF. 
var chunk = this._source.read(); 
if (chunk) this.push(chunk); 
} 
}; 


// Usage: 

// var parser = new SimpleProtocol(source); 

// Now parser is a readable stream that will emit 'header' 
// with the parsed header data. 


new stream.Readable([options]) 


e options Object 

o highWaterMark Number 在 停止 从 底层 资源 读 取 之 前 ， 在 内 部 缓冲 中 存储 
的 最 大 字 节 数 。 默 认为 16kb， 对 于 objectMode 则 是 16 

o encoding String 如 果 被 指定 ， 那 么 缓冲 将 被 利用 指定 编码 解码 为 字符 串 ， 
RUA null 

o objectMode Boolean 是 否 该 流 应 该 表现 如 一 个 对 象 的 流 。 意 思 是 
说 stream.read(n) 返回 一 个 单独 的 对 象 而 不 是 一 个 大 小 
为 n 的 Buffer >? RUA false 


在 实现 了 Readable 类 的 类 中 ， 请 确保 调用 了 Readable 构造 函数 ， 这 样 缓冲 设 
置 才 能 被 正确 的 初始 化 。 
readable. read(size) 
e size Number 异步 读 取 数据 的 字 节 数 
注意 : 实现 这 个 函数 ， 而 不 要 直接 调用 这 个 郊 数 。 


这 个 前 数 不 应 该 被 直接 调用 。 它 应 该 被 子 类 实现 ， 并 且 仅 被 Readable 类 的 内 部 方 
法 调用 。 


所 有 的 可 读 流 都 必须 实现 这 LIS 法 用 来 从 底层 资 oi J 中 获取 数据 2 


a 前 级 ， 因 为 它 对 于 类 是 内 部 的 ， 并 应 该 直接 被 用 户 的 程序 调 
你 应 在 你 的 拓展 类 里 覆盖 这 个 方法 。 

当 数 据 可 用 时 ， 调 用 readable.push(chunk) 方法 将 之 推 入 读 取 队列 。 如 果 方 法 

返回 false ， 那 么 你 应 当 停止 读 取 。 当 _read 方法 再 次 被 调用 ， 你 应 当 推 入 更 

多 数据 。 

参数 size 仅 作 查询 。“read” 调 用 返回 数据 的 实现 可 以 通过 这 个 参数 来 知道 应 当 抓 

取 多 少数 据 ; 其 余 与 之 无 关 的 实现 ， 比 如 TCP 或 TLS， 则 可 忽略 这 个 参数 ， 并 在 可 


用 时 返回 数据 。 例 如 ， 没 有 必要 “等 到 ”size 个 字 节 可 用 时 才 调 
用 stream.push(chunk) 。 


readable.push(chunk[, encoding]) 


e chunk Buffer | null | String 被 推 入 读 取 队 列 的 数据 块 
e encoding String 字符 串 数 据 块 的 编码 。 必 须 是 一 个 合法 的 Buffer 编码 ， 
如 'Utf8' 或 'ascii' 
e return Boolean 是 否 应 该 继续 推 入 
注意 : 这 个 函数 应 该 被 Readable 流 的 实现 者 调用 ， 而 不 是 消费 者 。 
_read() 函数 在 至 少 调用 一 次 push(chunk) 方法 前 ， 不 会 被 再 次 调用 。 


Readable 类 通过 在 readable 事件 触发 时 ， 调 用 read() 方法 将 数据 推 入 之 后 
用 于 读 出 数据 的 读 取 队列 来 工作 。 


push() a psi ae 。 如 果 它 的 参数 为 null » BA 
它 将 发 送 一 个 数据 结束 信号 ( EOF ) 。 


这 个 API 被 设计 为 尽 可 能 的 灵活 。 例 如 ， 你 可 能 正在 包 人 2 机 
制 和 一 个 数据 回调 函数 的 低级 别 源 。 那 那些 情况 下 ， 你 可 以 通过 以 下 方式 包装 这 些 


低级 别 源 : 


Stream 


// source is an object with readStop() and readStart() methods, 
// and an ‘ondata member that gets called when it has data, and 
// an `onend` member that gets called when the data is over. 


util.inherits(Sourcewrapper, Readable); 


function SourceWrapper(options) { 
Readable.call(this, options); 


this._source = getLowlevelSourceObject(); 
var self = this; 


// Every time there's data, we push it into the internal buffe 


this. _source.ondata = function(chunk) { 
// if push() returns false, then we need to stop reading fro 
m source 
if (!self.push(chunk ) ) 
self._source.readStop(); 


ti 
// When the source ends, we push the EOF-signaling ‘null chunk 


this. _source.onend = function() { 
self.push(null); 


jr 


// _read will be called when the stream wants to pull more data 

in 

// the advisory size argument is ignored in this case. 

SourceWrapper.prototype._read = function(size) { 
this._source.readStart(); 


ty 
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Class: stream.Writable 


276 


stream.Writable 是 一 个 被 设计 为 需要 实现 底层 的 _write(chunk, encoding, 
callback) 方法 的 抽象 类 。 


请 参阅 上 文 的 面向 流 消 费 者 的 API 来 了 解 如 何在 程序 中 消费 流 。 以 下 解释 了 如 果 在 
你 的 程序 中 实现 可 写 流 。 


new stream.Writable([options]) 


e options Object 

o highWaterMark Number write() 方法 开始 返回 false 的 缓冲 级 别 。 黑 
认为 16kb， 对 于 objectMode 流 则 是 16 

o decodeStrings Boolean 是 否 在 传递 给 write() 方法 前 将 字符 串 解 码 
成 Buffer ° RUA true 

o objectMode Boolean 是 否 write(any0bj) 为 一 个 合法 操作 。 如 果 设 置 
A true 你 可 以 写 入 任意 数据 而 不 仅 是 Buffer 或 字符 串 数 据 。 默 认 
为 false 


在 实现 了 writable 类 的 类 中 ， 请 确保 调用 了 writable iG HA > HAH IE 
置 才能 被 正确 的 初始 化 。 


writable. write(chunk, encoding, callback) 


e chunk Buffer | String 将 要 被 写 入 的 数据 块 。 除 非 decodeStrings 配置 被 设置 
为 false ， 否 则 将 一 直 是 一 个 buffer 

e encoding String 如 果 数 据 块 是 一 个 字符 串 ， 那 么 这 就 是 编码 的 类 型 。 如 果 是 一 
个 buffer ， 那 么 则 会 忽略 它 

e callback Function 当 你 处 理 完 给 定 的 数据 块 后 调用 这 个 函数 


所 有 的 Writable 流 的 实现 都 必须 提供 一 个 write() 方法 来 给 底层 资源 传输 数 
据 。 

这 个 函数 不 应 该 被 直接 调用 。 它 应 该 被 子 类 实现 ， 并 且 仅 被 writable 类 的 内 部 广 
法 调用 。 


回调 函数 使 用 标准 的 callback(error) 模式 来 表示 这 个 写 操 作成 功 或 发 生 了 错 


`g 
TR ° 


如 果 构 造 兄 数 选 项 中 设置 了 decodeStrings 标志 ， 那 么 数据 块 将 是 一 个 字符 串 而 
不 是 一 个 Buffer ， 编 码 将 会 决定 字符 囊 的 类 型 。 这 个 是 为 了 帮助 处 理 编码 字符 串 
的 实现 。 如 果 你 没有 明确 地 将 decodeStrings 选项 设 为 false ， 那 么 你 会 安全 
地 忽略 encoding 参数 ， 并 且 数 据 块 是 Buffer 形式 。 


这 个 元 数 有 一 个 下 划 线 前 级， 因为 它 对 于 类 是 内 部 的 ， 并 应 该 直接 被 用 户 的 程序 调 
用 。 你 应 在 你 的 拓展 类 里 覆盖 这 个 方法 。 


writable._writev(chunks, callback) 


e chunks Array 将 被 写 入 的 数据 块 数组 。 其 中 每 一 个 数据 都 有 如 下 格式 : { 
chunk: ..., encoding: ... } 
e callback Function 当 你 处 理 完 给 定 的 数据 块 后 调用 这 个 函数 


注意 : 这 个 函数 不 应 该 被 直接 调用 。 它 应 该 被 子 类 实现 ， 并 且 仅 被 writable 类 的 
内 部 方法 调用 。 


这 个 函数 对 于 你 的 实现 是 完全 可 选 的 。 大 多 数 情况 下 它 是 不 必 的 。 如 果实 现 ， 它 会 
被 以 所 有 滞留 在 写 入 队列 中 的 数据 块 调 用 。 


Class: stream.Duplex 
一 个 "“ 双 工 ? 流 既是 可 读 的 ， 又 是 可 写 的 。 如 TCP socket 连接 。 


注意 ， 和 你 实现 Readable 或 Writable 流 时 一 样 ， stream.Duplex 是 一 个 被 
设计 为 需要 实现 底层 的 _read(size) 和 _write(chunk, encoding, 
callback) 方法 的 抽象 类 。 


由 于 JavaScript 并 不 具备 多 继承 能 力 ， 这 个 类 是 继承 于 Readable 类 ， 并 寄生 
于 writable 类 。 所 以 为 了 实现 这 个 类 ， 用 户 需 要 同时 实现 低级 别 
的 _read(n) 方法 和 低级 别 的 _write(chunk, encoding, callback) 方法 。 


new stream.Duplex(options) 


e options Object 同时 传递 给 writable 和 Readable 构造 函数 。 并 且 和 包含 以 
下 属性 : 
o allowHalfOpen Boolean 默认 为 true 。 如 果 设 置 为 false ， 那 么 流 的 
可 读 的 一 端 结束 时 可 写 的 一 端 也 会 自动 结束 ， 反 之 亦 然 。 
o readableObjectMode Boolean 默认 为 false ， 为 流 的 可 读 的 一 端 设 


置 objectMode ° 4 objectMode A true NRA RR ° 
o writableObjectMode Boolean 默认 为 false ， 为 流 的 可 写 的 一 端 设 
置 objectMode ° 4 objectMode A true 时 没有 效果 。 


在 实现 了 Duplex 类 的 类 中 ， 请 确保 调用 了 Duplex 构造 函数 ， 这 样 缓冲 设置 才 
能 被 正确 的 初始 化 。 


Class: stream.Transform 


pie 出 于 输 入 存在 对 应 关 系 的 双 工 流 》 如 一 个 Zilib Fiz 或 一 


个 crypto 流 。 


输出 和 输出 并 不 需要 有 相同 的 大 小 ， 相 同 的 数据 块 数 或 同时 到 达 。 例 如 ， 一 个 哈 硕 
流 只 有 一 个 单独 数据 块 的 输出 当 输 入 结束 时 。 一 个 zlib 流 的 输出 比 其 输入 小 得 多 
或 大 得 多 。 


除了 实现 _read() 方法 和 _write() 方法 ， 转 换 流 还 必须 实 


I _transform() 方法 ， 并 且 可 选 地 实现 _flush() 方法 (参阅 下 文 ) 。 


new stream.Transform([options]) 
e options Object 同时 传递 给 writable 和 Readable 构造 函数 。 


在 实现 了 Transform 类 的 类 中 ， 请 确保 调用 了 Transform 构造 函数 ， 这 样 缓冲 
设置 才能 被 正确 的 初始 化 。 


transform._transform(chunk, encoding, callback) 


e chunk Buffer | String 将 要 被 写 入 的 数据 块 。 除 非 decodeStrings 配置 被 设置 
为 false ， 否 则 将 一 直 是 一 个 buffer 

e encoding String 如 果 数 据 块 是 一 个 字符 串 ， 那 么 这 就 是 编码 的 类 型 。 如 果 是 一 
个 buffer， 那 么 则 会 忽略 它 

e callback Function 当 你 处 理 完 给 定 的 数据 块 后 调用 这 个 函数 


个 函数 不 应 该 被 直接 调用 。 它 应 该 被 子 类 实现 ， 并 且 仅 被 Transform 类 的 内 部 
on. 


所 有 Transform 流 的 实现 都 必须 提供 一 个 o transform 方法 来 接受 输入 和 产生 输 
出 o 


在 Transform 类 中 ， _transform 可 以 做 需要 做 的 任何 事 ， 如 处 理 需 要 写 入 的 字 
节 ， 将 它们 传递 给 可 写 端 ， 异 步 MJO， 等 等 。 


调用 transform.push(outputChunk) 0 次 或 多 次 来 从 输入 的 数据 块 产生 输出 ， 取 
决 于 你 想 从 这 个 数据 块 中 输出 多 少数 据 作 为 结果 。 


仅 当 目前 的 数据 块 被 完全 消费 后 ， 才 会 调用 回调 函数 。 注 意 ， 对 于 某 些 特殊 的 输入 
可 能 会 没有 和 输出。 如果 你 将 数据 作为 第 二 个 参数 传 入 回调 函数 ， 那 么 数据 将 被 传递 
给 push 方法 。 换 名 话说 ， 下 面 的 两 个 例子 是 相等 的 : 


transform.prototype._transform = function (data, encoding, callb 
ack) { 

this.push(data); 

callback(); 
} 


transform.prototype._transform = function (data, encoding, callb 
ack) { 
callback(null, data); 


} 


这 个 函数 有 一 个 下 划 线 前 组， 因为 它 对 于 类 是 内 部 的 ， 并 应 该 直接 被 用 户 的 程序 调 
用 。 你 应 在 你 的 拓展 类 里 覆盖 这 个 方法 。 


transform._flush(callback) 


e callback Function 当 你 排 室 了 所 有 剩余 数据 后 ， 这 个 回调 函数 会 被 调用 


注意 : 这 个 有 函数 不 应 该 被 直接 调用 。 它 应 该 被 子 类 实现 ， 并 且 仅 被 Transform 类 

的 内 部 方法 调用 。 

在 一 些 情景 中 ， 你 的 转换 操作 需要 在 流 的 末尾 多 发 生 一 点 点 数据 。 例 如 ， 一 

个 Zlib 压缩 流 会 存储 一 些 内 部 状态 以 便 它 能 优化 压缩 输出 。 但 是 在 最 后 ， 它 需要 
尽 可 能 好 得 处 理 这 些 留 下 的 东西 来 使 数据 完整 。 

在 这 种 情况 中 ， 您 可 以 实现 一 个 flush 方法 ， 它 会 在 最 后 被 调用 ， 在 所 有 写 入 数 


据 被 消费 、 但 在 触发 end 表示 可 读 端 到 达 末 尾 之 前 。 和 _transform 一 样 ， 只 需 
在 写 入 操作 完成 时 适当 地 调用 transform.push(chunk) KAŽ ° 


这 个 函数 有 一 个 下 划 线 前 级， 因为 它 对 于 类 是 内 部 的 ， 并 应 该 直接 被 用 户 的 程序 调 
用 。 你 应 在 你 的 拓展 类 里 履 盖 这 个 方法 。 


Events: 'finish' 和 'end' 


finish 和 end 事件 分 别 来 自 于 父 类 writable 和 Readable ° finish 事件 
在 end() 方法 被 调用 以 及 所 有 的 输入 被 _transform 方法 处 理 后 触发 。 end 事 
件 在 所 有 的 在 flush 方法 的 回调 兄 数 被 调用 后 的 数据 被 输出 后 触发 。 


Example: SimpleProtocol 解释 器 v2 


上 文中 的 简单 协议 解释 器 可 以 简单 地 通过 高 级 别 的 Transform 流 更 好 地 实现 。 与 
上 文 例子 中 的 parseHeader 和 SimpleProtocol v1 相似 。 


在 这 个 例子 中 ， 没 有 从 参数 中 提供 输入 ， 然 后 将 它 导 流 至 解释 器 中 ， 这 更 符 
合 node.js 的 使 用 习惯 。 


var util = require('util'); 
var Transform = require('stream').Transform; 
util.inherits(SimpleProtocol, Transform); 


function SimpleProtocol(options) { 
if (!(this instanceof SimpleProtocol) ) 
return new SimpleProtocol(options); 


Transform.call(this, options); 
this. _inBody = false; 
this._sawFirstCr = false; 
this._rawHeader = []; 
this.header = null; 


SimpleProtocol.prototype. transform = function(chunk, encoding, 
done) { 
if (!this._inBody) { 
// check if the chunk has a \n\n 
var split = -1; 
for (var i = 0; i < chunk.length; i++) { 
if (chunk[i] === 10) { // '\n' 


if (this._sawFirstCr) { 


split = i; 
break; 
} else { 
this._sawFirstCr = true; 
} 
} else { 
this._sawFirstCr = false; 
} 
} 
if (split === -1) { 


// still waiting for the \n\n 
// stash the chunk, and try again. 
this. _rawHeader .push(chunk) ; 
} else { 
this. _inBody = true; 
var h = chunk.slice(0, split); 
this. _rawHeader.push(h); 
var header = Buffer.concat(this. _rawHeader).toString(); 
try { 
this.header = JSON.parse(header); 
} catch (er) { 
this.emit('error', new Error('invalid simple protocol da 
ta')); 
return; 
} 
// and let them know that we are done parsing the header. 
this.emit('header', this.header); 


// now, because we got some extra data, emit this first. 
this.push(chunk.slice(split)); 
} 
} else { 
// from there on, just provide the data to our consumer as-i 


this.push(chunk); 


} 
done(); 


$? 


// Usage: 

// var parser = new SimpleProtocol(); 

// source.pipe(parser ) 

// Now parser is a readable stream that will emit 'header' 
// with the parsed header data. 


Class: stream.PassThrough 


入 的 流 简单 地 传递 给 输出 。 它 的 主要 目的 是 


这 是 一 个 Transform 流 输 
构建 特殊 流 的 情况 下 可 能 有 用 。 


的 实现 。 将 和 
用 来 演示 和 测试 ， 但 它 在 某 些 需要 构 


简化 的 构造 器 API 
可 以 简单 的 构造 流 而 不 使 用 继承 。 
这 可 以 通过 调用 合适 的 方法 作为 构造 函数 和 参数 来 实现 : 


例子 : 


Readable 


var readable = new stream.Readable({ 
read: eae { 


} 
}); 


Writable 


var writable = new stream.Writable({ 
write: function(chunk, encoding, next) { 
// sets this._write under the hood 
} 
}); 


H OE 


var writable = new stream.Writable({ 
writev: function(chunks, next) { 
// sets this._writev under the hood 
} 
}); 


Duplex 


var duplex = new stream.Duplex({ 
read: function(n) { 
// sets this._read under the hood 
tr 
write: function(chunk, encoding, next) { 
// sets this._write under the hood 
} 
}); 


On 


var duplex = new stream.Duplex({ 
read: function(n) { 
// sets this._read under the hood 
ty 
writev: function(chunks, next) { 
// sets this._writev under the hood 
} 
}); 


Transform 


var transform = new stream.Transform({ 
transform: function(chunk, encoding, next) { 
// sets this._transform under the hood 
ty 
flush: function(done) { 
// sets this. flush under the hood 
} 
}); 


44 


流 : 内 部 细节 

Ber 

Writable 流 和 Readable 流 都 会 分 别 在 一 个 内 部 的 

叫 writableState.buffer X _readableState.buffer 的 对 象 里 缓冲 数据 。 
潜在 的 被 缓冲 的 数据 量 取决 于 被 传递 给 构造 函数 的 highwaterMark 参数 。 


在 Readable 流 中 ， 当 其 的 实现 调用 stream.push(chunk) 时 就 会 发 生 缓冲 。 如 
果 流 的 消费 者 没有 调用 stream.read() ， 那 么 数据 就 会 保留 在 内 部 队列 中 直到 它 
被 消费 。 


在 writable 流 中 ， 当 用 户 重 复 调 用 stream.write(chunk) 时 就 会 发 生 缓冲 ， 
甚至 是 当 write() 返回 false 时 。 


流 ， 尤 其 是 pipe() 方法 的 初衷 ， 是 限制 数据 的 滞留 量 在 一 个 可 接受 的 水 平 ， 这 样 
才 使 得 不 同 传输 速度 的 来 源 和 目标 不 会 海 没 可 用 的 内 存 。 


stream.read(0) 


在 一 些 情况 下 ， 你 想 不 消 费 任何 数据 而 去 触发 一 次 底层 可 读 流 机 制 的 刷新 。 你 可 以 
调用 stream.read(0) ， 它 总 是 返回 null 。 


如 果 内 部 的 读 缓 冲 量 在 highwaterMark 之 下 ， 并 且 流 没有 正在 读 取 ， 那 么 调 
用 read(0) 将 会 触发 一 次 低级 别 的 _read 调用 。 


ww 做 。 但 是 ， 你 可 能 会 在 node.js 的 Readable 流 类 的 内 部 
代码 的 几 处 看 到 这 个 。 


stream.push(") 


推 入 一 个 0 字 节 的 字符 串 或 Buffer (不 处 于 对 象 模式 ) 有 一 个 有 趣 的 副作用 。 因 
为 这 是 一 个 stream.push() 的 调用 ， 它 将 会 结束 读 取 进 程 。 但 是 ， 它 不 添加 任何 
数据 到 可 读 缓 冲 中 ， 所 以 没有 任何 用 户 可 消费 的 数据 。 


在 极 少 的 情况 下 ， 你 ee a 但 你 的 消费 者 同 过 调 
用 stream.read(0) 来 得 知 合适 再 次 检查 。 在 这 样 的 情况 下 ， 你 可 以 调 
用 stream.push('') ° 


今 为 止 ， 这 个 功能 的 唯一 使 用 之 处 是 在 tls.cryptoStream 类 中 ， 它 将 
和 node.js 的 1.0 版 本 中 被 废弃 。 如 果 你 发 现 你 不 得 不 使 用 stream.push('') ， 
请 考虑 使 用 另外 的 方式 。 因 为 这 几乎 表示 发 生 了 某 些 可 怕 的 错误 。 


与 旧版 本 的 Node.js 的 兼容 性 
在 Node.js 的 0.10 版 本 之 前 ， 可 读 流 接 口 非 常 简单 ， 并 且 功 能 和 功用 都 不 强 。 


e data 事件 会 立刻 触发 ， 而 不 是 等 待 你 调用 read() 方法 。 如 果 你 需要 进行 
一 些 I/0 操作 来 决定 是 否 处 理 数 据 ， 那 么 你 只 能 将 数据 存储 在 某 些 缓冲 区 中 
以 防 数 据 流 失 。 

e pause() 仅 供 查询 ， 并 不 保证 生效 。 这 意味 着 你 还 是 要 准备 接收 data 事件 
在 流 已 经 处 于 暂停 模式 中 时 。 


在 node.js V1.0 和 Node.js v0.10 中 ， 下 文 所 述 的 Readable 类 添加 进来 。 为 
了 向 后 兼容 性 ， 当 一 个 data 事件 的 监听 器 被 添加 时 或 resume() 方法 被 调用 

时 ， 可 读 流 切 换 至 流动 模式 。 其 作用 是 ， 即 便 您 不 使 用 新 的 read() 方法 

和 readable 事件 ， 您 也 不 必 担 心 丢 失 数据 块 。 


大 多 数 程 序 都 会 保持 功能 正常 ， 但 是 ， 以 下 有 一 些 边界 情况 : 


o 没有 添加 任何 data 事件 
e 从 未 调用 resume() 方法 
e 流 没 有 被 导 流 至 任何 可 写 的 目 标 


例如 ， 考 虑 以 下 代码 : 


// WARNING! BROKEN! 
net.createServer(function(socket) { 


// we add an ‘end' method, but never consume the data 
socket.on('end', function() { 

// It will never get here. 

socket.end('I got your message (but didnt read it)\n'); 


}); 
}).listen(1337); 
在 Node.js v0.10 前 ， 到 来 的 信息 数据 会 被 简单 地 丢弃 。 但 是 在 node.js v1.0 
和 Node.js V0.10 后 ， socket 会 被 永远 暂停 。 


解决 方案 是 调用 resume() 方法 来 开启 数据 流 : 


// Workaround 
net.createServer(function(socket) { 


socket.on('end', function() { 
socket.end('I got your message (but didnt read it)\n'); 


}); 


// start the flow of data, discarding it. 
socket.resume(); 


}).listen(1337); 


除了 新 的 Readable 流 切换 至 流动 模式 之 外 ， 在 v0.10 之 前 的 流 可 以 被 使 
用 wrap() JEX ° 


对 月 模式 
通常 情况 下 ， 流 仅 操 作 字 符 串 和 Buffer ° 


处 于 对 象 模 式 中 的 流 除 了 Buffer 和 字符 串 外 ， 还 能 读 出 普通 
的 JavaScirpt 值 。 


处 于 对 象 模 式 中 的 可 读 流 在 调用 stream.read(size) 后 只 会 返回 单个 项 目 ， 不 
论 size 参数 是 什么 


处 于 对 象 模式 中 的 可 写 流 总 是 忽略 stream.write(data, encoding) 中 
的 encoding 参数 。 


对 于 处 于 对 象 村 BAT Ne > AEN I 仍然 保留 它 的 特殊 意义 。 也 就 是 说 ， 对 于 
对 象 模式 的 可 读 流 ， stream.read() 返回 一 个 null jg tala 没有 更 多 的 数据 
了 ， 并 且 stream.push(null) 会 发 送 一 个 文件 末端 信号 ( EOF ) ° 


核心 node.js 中 没有 流 是 对 象 模式 的 。 这 个 模式 仅仅 供用 户 的 流 库 使 用 。 


你 应 当 在 子 类 的 构造 函数 的 options 参数 对 象 中 设置 对 象 模式 。 在 流 的 过 程 中 设 
置 对 象 模 式 时 不 安全 的 。 


对 于 双 工 流 ， 人 oan oe 和 writableObjectMode 1% 
置 可 读 端 和 可 写 端 。 这 些 配置 可 以 被 用 来 通过 转换 流 实现 解释 器 和 序列 化 器 


var util = require('util'); 

var StringDecoder = require('string_decoder').StringDecoder ; 
var Transform = require('stream').Transform; 
util.inherits(JSONParseStream, Transform); 


// Gets \n-delimited JSON string data, and emits the parsed obje 
cts 
function JSONParseStream() { 
if (!(this instanceof JSONParseStream) ) 
return new JSONParseStream(); 


Transform.call(this, { readableObjectMode : true }); 


this._buffer = ''; 
this._decoder = new StringDecoder('utf8'); 


JSONParseStream.prototype. transform = function(chunk, encoding, 
cb) { 

this._buffer += this. _decoder.write(chunk); 

// split on newlines 

var lines = this._buffer.split(/\r?\n/); 

// keep the last partial line buffered 


this._buffer = lines.pop(); 
for (var 1 = 0; 1 < lines.length; l++) { 
var line = lines[1]; 
ERY 
var obj = JSON.parse(line); 
} catch (er) 4 
this.emit('error', er); 
return; 
} 
// push the parsed object out to the readable consumer 
this.push(obj); 
} 
cb(); 
}; 


JSONParseStream.prototype._flush = function(cb) { 
// Just handle any leftover 
var rem = this._buffer.trim(); 
if (rem) { 
cGy 
var obj = JSON.parse(rem); 
} catch (er) 4 
this.emit('error', er); 
return; 
} 
// push the parsed object out to the readable consumer 
this.push(obj); 
} 
cb(); 
}; 


StringDecoder 


ACE 2 - Fh 


通过 require('string_decoder') 来 使 用 这 个 模块 。 StringDecoder 解码 一 
个 buffer 为 一 个 字符 串 。 它 是 一 个 buffer ,toString() 的 简单 接口 ， 但 是 提供 
了 utf8 的 额外 支持 。 


var StringDecoder = require('string_decoder').StringDecoder ; 
var decoder = new StringDecoder('utf8'); 


var cent = new Buffer([0xC2, OxA2]); 
console. log(decoder.write(cent)); 


var euro = new Buffer([OxE2, 0x82, OxAC]); 


console. log(decoder.write(euro)); 


Class: StringDecoder 


接受 一 个 单独 的 参数 ， 即 编码 ， 默 认为 utf8。 


decoder.write(buffer) 


返回 被 解码 的 字符 囊 。 


decoder.end() 


返回 遗留 在 buffer 中 的 所 有 末端 字 节 。 


Timers 


稳定 度 : 3 - 锁定 
所 有 的 定时 器 防 数 都 是 全 局 的 。 当 需要 使 用 它们 时 ， 不 必 通 过 require() ° 


setTimeout(callback, delay[, arg][, ...]) 


在 指定 的 延 时 (毫秒 ) 后 执行 一 次 回调 函数 。 返 回 一 个 可 以 被 调 
用 clearTimeout()  timeoutObject 。 可 选 的 ， 你 可 以 传递 回调 函数 的 参 
数 。 


需要 注意 的 是 ， 你 的 回调 函数 可 以 不 会 在 精确 的 在 指定 的 毫秒 延 时 后 执行 - 
node.js 对 回调 部 数 执行 的 精确 时 间 以 及 顺序 都 不 作 保证 。 回 调 函 数 的 执行 点 会 

尽量 接近 指定 的 延 时 。 

clearTimeout(timeoutObject) 


阻止 一 个 timeout 的 触发 。 


setinterval(callback, delay[, arg][, ...]) 

在 每 次 到 达 了 指定 的 延 时 后 ， 都 重复 执行 回调 函数 。 返 回 一 个 可 以 被 调 

用 clearInterval() 的 intervalObject 。 可 选 的 ， 你 可 以 传递 回调 函数 的 参 
数 。 

clearlnterval(intervalObject) 


阻止 一 个 interval 的 触发 。 


unref() 


setTimeout 和 setInterval 的 返回 值 也 有 一 个 timer.unref() 方法 ， 这 个 方 
法 允许 你 创建 一 个 当 它 是 事件 循环 中 的 仅 剩 项 时 ， 它 不 会 保持 程序 继续 运行 的 定 
时 器 。 如 果 一 个 定时 器 已 经 被 unref ， 再 次 调用 unref 不 会 有 任何 效果 。 


在 setTimeout 的 情况 下 ， 当 你 调用 unref 时 ， 你 创建 了 一 个 将 会 唤醒 事件 循环 
的 另 一 个 定时 器 。 创 建 太 多 这 样 的 定时 器 会 影响 时 间 循 环 的 性 能 -- 请 明智 地 使 用 。 


ref() 


如 果 你 先前 对 一 个 定时 器 调用 了 unref() ， 你 可 以 调用 ref() 来 明确 要 求 定 时 
器 要 保持 程序 运行 。 如 果 一 个 定时 器 已 经 被 ref ， 再 次 调用 ref 不 会 有 任何 效 
果 。 


setimmediate(callback[, arg][, ...]) 


在 下 一 次 I/O 事 件 循 环 后 ， 在 setTimeout 和 setInterval 前 ， E AA 
数 。 返 回 一 个 可 以 被 clearImmediate()  immediateObject 。 可 选 的 ， 你 可 
以 传递 回调 函数 的 参数 。 


由 setImmediate 创建 的 回调 函数 会 被 有 序 地 排队 。 每 一 次 事件 循环 迭代 时 ， 整 
个 回调 函数 队列 都 会 被 处 理 。 如 果 你 在 一 个 执行 中 的 回调 函数 里 调用 

了 setImmediate ， 那 么 这 个 setImmediate 中 的 回调 函数 会 在 下 一 次 事件 循环 
迭代 时 被 调用 。 


clearlmmediate(immediateObject) 


阻止 一 个 immediate 的 触发 。 


TLS (SSL) 


稳定 度 : 2 -稳定 
通过 require('tls') 来 使 用 这 个 模块 。 


tls 模块 使 用 OpenSSL 来 提供 传输 层 的 安全 和 /或 安全 socket 层 : 已 加 密 的 流 


a4 


通信 。 


TLS/SSL 是 一 种 公 / 私 钥 架 构 。 每 个 客户 端 和 每 个 服务 器 都 必须 有 一 个 私 钥 。 一 个 私 
钥 通 过 像 如 下 的 方式 创建 


openssl genrsa -out ryans-key.pem 2048 


所 有 的 服务 器 和 部 分 的 客户 端 需要 一 个 证 书 。 证 书 是 被 CA 签名 或 自 签 名 的 公 钥 。 获 
取 一 个 证 书 第 一 步 是 创建 一 个 “证 书签 署 请 求 ( Certificate Signing 
Request) ”(CSR) 文件 。 通 过 : 


openssl req -new -sha256 -key ryans-key.pem -out ryans-csr.pem 


要 通过 CSR 创 建 一 个 自 签 名 证 书 ， 通 过 : 


openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out 
ryans-cert.pem 


另外 ， 你 也 可 以 把 CSR 交 给 一 个 CA 请 求 签名 © 


为 了 完全 向 前 保密 (PFS) > ELF WEAK HA: 


openssl dhparam -outform PEM -out dhparam.pem 2048 


openssl pkcsi2 -export -in agent5-cert.pem -inkey agent5-key.pem 
\ 
-certfile ca-cert.pem -out agent5.pfx 


e in: 证 书 

e inkey: 444A 

e certfile: 将 所 有 CA certs 串联 在 一 个 文件 中 ， 就 像 cat cal-cert.pem 
ca2-cert.pem > ca-cert.pem 。 


端 发 起 的 重新 协商 攻击 的 减 绥 


TLS 协 议 让 客户 A T 分 的 TLS 会 话 。 不 幸 的 是 ， 会 话 重 协商 需要 
不 相称 的 服务 器 端 资源 ， 这 它 可 能 成 为 潜在 的 DOS 攻 击 。 


为 了 减缓 这 种 情况 ， 重 新 协商 被 限制 在 了 每 10 分 钟 最 多 3 次 。 当 超过 阀 值 
时 ， tls.TLSSocket 会 触发 一 个 错误 。 阀 值 是 可 以 调整 的 : 


e tls.CLIENT_RENEG LIMIT: 重新 协商 限制 ， 默 认为 3 。 

e tis.CLIENT_RENEG_WINDOW: 重新 协商 窗口 ( 秒 ) ， 默 认为 10 分 钟 。 
除非 你 知道 你 在 做 什么 ， 否 则 不 要 改变 默认 值 。 
为 了 测试 你 的 服务 器 ， 使 用 openssl s_client -connect address:port 来 连接 
它 ， 然 后 键入 R<CR> (字母 R 加 回 车 ) 多 次 。 
NPN 和 SNI 


NPN (下 个 协议 协商 ) PSNI (服务 器 名 称 指示 ) 都 是 TLS 握 手 拓 展 ， 它 们 允许 
你 : 


e NPN - 通过 多 个 协议 (HTTP? SPDY) 使 用 一 个 TLS 服 务 器 。 
e SNI- 通过 多 个 有 不 同 的 SSL 证 书 的 主机 名 来 使 用 一 个 TLS 服 务 器 。 
完全 向 前 保密 


术语 "向 前 保密 "或 “完全 向 前 保密" 描述 了 一 个 密 负 -协商 (如 密 钢 -交换 ) 方法 的 特 
性 。 事 实 上 ， 它 意味 着 ， 甚 至 是 当 (你 的 ) 服务 器 的 私 铀 被 窃取 了 ， 窗 取 者 也 只 能 
在 他 成 功 获得 所 有 会 话 产生 的 密 钢 对 时 ， 才 能 解码 信息 。 


它 通过 在 每 次 握手 中 (而 不 是 所 有 的 会 话 都 是 同样 的 密 钥 ) 随机 地 产生 用 于 密 钥 - 协 
商 的 密 钥 对 来 实现 。 实 现 了 这 个 技术 的 方法 被 称 作 “ephemeral”。 


目前 有 两 种 普遍 的 方法 来 实现 完全 向 前 保密 : 


e DHE -一 个 迪 菲 - 赫 尔 曼 密 钥 -协商 协议 的 ephemeral MA ° 
e ECDHE - 一 个 椭圆 曲线 迪 菲 - 幸 尔 曼 密 钥 -协商 协议 的 ephemeral 版 本 。 


ephemeral 方法 可 能 有 一 些 性 能 问题 ， 因 为 密 铀 的 生成 是 昂贵 的 。 


tls.getCiphers() 
返回 支持 的 SSL 加 密 器 的 名 字数 组 。 
例子 : 


var ciphers = tls.getCiphers(); 
console.log(ciphers); // ['AES128-SHA', 'AES256-SHA' 


tls.createServer(options[, secureConnectionListener]) 


创 一 个 新 的 tls.Server 实例 。 connectionListener 参数 被 自动 添加 
为 secureConnection 事件 的 监听 器 。 options 参数 可 以 有 以 下 属性 : 


e pfx: 一 个 包含 PFX 或 PKCS12 格式 的 私 钥 ， 加 密 赁 证 和 CA 证 书 的 字符 串 
或 buffer ° 


e key: 一 个 带 着 PEM 加 密 私 钥 的 字符 串 (可 以 是 密 钥 数组 ) ( 必 选 ) 。 
e passphrase: 一 个 私 钥 或 pfx 密码 字符 串 。 


e cert: 一 个 包含 了 PEM 格式 的 服务 器 证 书 密 钥 的 字符 串 或 buffer (可 以 
是 cert 数组 ) ( 必 选 ) 。 


e ca: 一 个 PEM 格式 的 受信 任 证 书 的 字符 串 或 buffer 数组 。 如 果 它 被 忽略 ， 
将 使 用 一 些 众所周知 的 “ 根 "CA， 像 VeriSign 。 这 些 被 用 来 授权 连接 。 


e crl :一 个 PEM 编码 的 证 书 撤销 列表 (Certificate Revocation List) 字符 串 或 字 
符 串 列表 。 

e ciphers: 一 个 描述 要 使 用 或 排除 的 加 密 器 的 字符 串 ， 通 过 ; TB o RAKI do R 
器 套件 是 : 


ECDHE -RSA-AES128 -GCM-SHA256: 
ECDHE -ECDSA-AES128 -GCM-SHA256: 
ECDHE -RSA-AES256 - GCM-SHA384: 
ECDHE -ECDSA- AES256 -GCM-SHA384: 
DHE - RSA-AES128-GCM-SHA256: 
ECDHE-RSA-AES128 -SHA256: 

DHE -RSA-AES128-SHA256: 

ECDHE -RSA-AES256 - SHA384: 

DHE -RSA-AES256 - SHA384 : 
ECDHE-RSA-AES256 -SHA256: 

DHE -RSA-AES256-SHA256: 

HIGH: 

!aNULL: 

!eNULL: 

! EXPORT : 

! DES: 

IRC4: 

!MD5: 

! PSK: 

! SRP: 

!CAMELLIA 


默认 的 加 密 器 套件 更 倾向 于 Chrome's 'modern cryptography' setting 的 
GCM 加 密 器 ， 也 倾向 于 PFC 的 ECDHE 和 DHE 加 密 器 ， 它 们 提供 了 一 些 向 后 兼容 
性 o 


鉴于 specific attacks affecting larger AES key sizes ， 所 以 更 倾向 于 使 
用 128 位 的 AES 而 不 是 192 和 256 位 的 AES ° 


旧 的 依赖 于 不 安全 的 和 弃 用 的 RC4 或 基于 DES 的 加 密 器 ( 像 IE6) 的 客户 端 将 不 能 
完成 默认 配置 下 的 握手 。 如 果 你 必须 支持 这 些 客 户 端 ， TLS 推 荐 规范 可 能 提供 了 一 
个 兼容 的 加 密 器 套件 。 更 多 格式 细节 ， 参 阅 OpenSSL cipher list format 


documentation ° 


e ecdhCurve: 一 个 描述 用 于 ECDH 密 钥 协商 的 已 命名 的 椭圆 的 字符 串 ， 如 果 要 
禁用 ECDH ， 就 设置 为 false 。 


默认 值 为 prime256v1 (NIST P-256) 。 使 用 crypto.getCurves() 来 获取 一 个 
可 用 的 椭圆 列表 。 在 最 近 的 发 行 版 中 ， 运 行 Openssl ecparam -list_curves 命 
令 也 会 展示 所 有 可 用 的 椭圆 的 名 字 和 描述 。 


e dhparam: 一 个 包含 了 迪 菲 - 幸 尔 曼 参 数 的 字符 串 或 buffer > LRA RAHAT 


保密 。 使 用 openssl dhparam 来 创建 它 。 它 的 密 钥 长 度 需 要 大 于 等 于 1024 字 
节 ， 否 则 会 抛 出 一 个 错误 。 强 力 推荐 使 用 2048 或 更 多 位 ， 来 获取 更 高 的 安全 
性 。 如 果 参 数 被 忽略 或 不 合法 ， 它 会 被 默默 丢弃 并 且 DHE 加 密 器 将 不 可 用 。 


handshakeTimeout: 当 SSL/TLS 握 手 在 这 个 指定 的 毫秒 数 后 没有 完成 时 ， 终 止 
这 个 链接 。 默 认为 120 秒 。 


当 握 手 超 时 时 ， tls.Server 会 触发 一 个 clientError 事件 。 


honorCipherOrder : 选择 一 个 加 密 器 时 ， 使 用 使 用 服务 器 的 首选 项 而 不 是 客户 
端的 首选 项 。 默 认为 true 。 


requestCert: 如 果 设 置 为 true ， 服 务 器 将 会 向 连接 的 客户 端 请 求 一 个 证 书 ， 
并 且 试 图 验证 这 个 证 书 。 黑 认为 true 。 


rejectUnauthorized: 如 果 设 置 为 true ， 服 务 器 会 拒绝 所 有 没有 在 提供 的 CA 
列表 中 被 授权 的 客户 端 。 只 有 在 requestCert 为 true 时 这 个 选项 才 有 效 。 
默认 为 false ° 


NPNProtocols: 一 个 可 用 的 NPN 协议 的 字符 串 或 数组 (协议 应 该 由 它们 的 优 
先 级 被 排序 ) 。 


SNICallback(servername, cb): 当 客 户 端 支持 SNI TLS 扩展 时 ， 这 个 函数 会 
被 调用 。 这 个 郊 数 会 被 传递 两 个 参数 : servername 和 cb。 SNICallback 必须 
执行 cb(null，ctx) , ctx 是 一 个 SecureContext 实例 (你 可 以 使 

用 tls.createSecureContext(...) 来 获取 合适 的 SecureContext ) ° # 
果 SNICallback 没有 被 提供 - 默认 的 有 高 层次 API 的 回调 函数 会 被 使 用 ( 参 
AFX) 。 


sessionTimeout: 一 个 指定 在 TLS 会 话 标 识 符 和 和 TLS 会话 门票 (tickets) 被 服务 
器 创建 后 的 超时 时 间 。 更 多 详情 参阅 SSL_CTX_set_timeout ° 


ticketKeys: —* 16°F FIA > 16°F Phmac# 4A > 16°F VW AECH 4A 204948 
FY buffer 。 你 可 以 使 用 它 在 不 同 的 tls 服务 器 实例 上 接受 tls 会 话 门 


o 


He 


注意 : 会 在 cluster 模块 工作 进程 间 自 动 


e sessionldContext: 一 个 包含 了 会 话 恢复 标识 符 的 字符 事 。 如 
果 requestCert A true ， 默 认 值 是 通过 命令 行 生 成 的 MD5 哈 希 值 。 否 则 ， 
就 将 不 提供 默认 值 。 


e secureProtocol: 将 要 使 用 的 SSL 方 法 ， 举 例 ， SSLv3_method 将 强制 使 用 
SSL v3。 可 用 的 值 取 决 于 OpenSSL 的 安装 和 SSL_METHODS 常量 中 被 定义 的 


值 。 


下 面 是 一 个 简单 应 答 服务 器 的 例子 : 


var tls = require('tls'); 
var fs = require('fs'); 


var options = { 
key: fs.readFileSync('server-key.pem'), 
cert: fs.readFileSync('server-cert.pem'), 


// This is necessary only if using the client certificate auth 
entication. 
requestCert: true, 


// This is necessary only if the client uses the self-signed c 
ertificate. 
ca: [ fs.readFileSync('client-cert.pem') ] 


Po 


var server = tls.createServer(options, function(socket) { 
console.log('server connected', 
socket.authorized ? 'authorized' : 'unauthorized') 


socket.write("welcome!\n"); 
socket.setEncoding('utf8'); 
socket .pipe(socket); 

+); 

server.listen(8000, function() { 
console.log('server bound'); 


}); 


se 


var tls = require('tls'); 
var fs = require('fs'); 


var options = { 
pfx: fs.readFileSync('server.pfx'), 


// This is necessary only if using the client certificate auth 
enticatiion. 
requestCert: true, 


Po 


var server = tls.createServer(options, function(socket) { 
console.log('server connected', 
socket.authorized ? 'authorized' : 'unauthorized') 


socket.write("welcome!\n"); 
socket.setEncoding('utf8'); 
socket.pipe(socket); 

+); 

server.listen(8000, function() { 
console.log('server bound'); 


}); 


45 


你 可 以 通过 openssl s_client 来 连接 服务 器 : 


an 


openssl s_client -connect 127.0.0.1:8000 


tls.connect(options[, callback]) 


tls.connect(port[, host][, options][, callback]) 


根据 给 定 的 端口 和 主机 (BAPI) 或 options.port 和 options.host 创建 一 个 
新 的 客户 端 连接 。 如 果 和 忽略 了 主机 ， 默 认为 localhost 。 options 可 是 一 个 含 
有 以 下 属性 的 对 多 : 


host: 客户 端 应 该 连接 到 的 主机 。 
port: 客户 端 应 该 连接 到 的 端口 。 


socket: 根据 给 定 的 socket 的 来 建立 安全 连接 ， 而 不 是 创建 一 个 新 
的 socket 。 如 果 这 个 选项 被 指定 ，host 和 port 会 被 忽略 。 


path: 创建 到 path 的 Unix socket 连接 。 如 果 这 个 选项 被 指 

定 ， host 和 port 会 被 忽略 。 

pfx: 一 个 PFX 或 PKCS12 格式 的 包含 了 私 钥 ， 证 书 和 CA 证 书 的 字符 串 
或 buffer 。 


key: 一 个 PEM 格式 的 包含 了 客户 端 私 钥 的 字符 串 或 buffer 〈 可 以 是 密 钥 的 
数组 ) 。 


passphrase: 私 钥 或 pfx 的 密码 字符 串 。 


cert: 一 个 PEM 格式 的 包含 了 证 书 密 钥 的 字符 串 或 buffer (可 以 是 密 钥 的 数 
组 ) 。 


ca: 一 个 PEM 格式 的 受信 任 证 书 的 字符 串 或 buffer 数组 。 如 果 它 被 忽略 ， 
将 使 用 一 些 众 所 周知 的 CA， 像 VeriSign 。 这 些 被 用 来 授权 连接 。 


ciphers: 一 个 描述 了 要 使 用 或 排除 的 加 密 器 ， 由 ; 分 割 。 使 用 的 黑 认 加 密 器 套 
件 与 tls.createServer 使 用 的 一 样 。 


rejectUnauthorized: 若 被 设置 为 true ， 会 根据 提供 的 CA 列表 来 验证 服务 器 
证 书 。 当 验证 失败 时 ， 会 触发 error 事件 ; err.code 包含 了 一 个 
OpenSSL #41443 ° RIA true 。 


NPNProtocols: 包含 支持 的 NPN 协 议 的 字符 串 或 buffer 数组 。 buffer 必 
须 有 以 下 格式 : 0Qx05hello0x05world ， 第 一 个 字 节 是 下 一 个 协议 名 的 长 度 
(传递 数组 会 更 简单 : ['hello', 'world'] ) ° 


servername: SNI TLS 扩展 的 服务 器 名 。 


checkServerldentity(servername, cert): 为 根据 证 书 的 服务 器 主机 名 检查 提供 
了 和 履 盖 。 必 须 在 验证 失败 时 返回 一 个 错误 ， 验 证 通过 时 返回 undefined 。 


secureProtocol: 将 要 使 用 的 SSL 方 法 ， 举 例 ， SSLv3_method 将 强制 使 用 
SSL v3。 可 用 的 值 取决 于 OpenSSL 的 安装 和 SSL_METHODS 常量 中 被 定义 的 


值 。 


e session: 一 个 Buffer 实例 ， 包 含 了 TLS 会 话 。 
callback 参数 会 被 自动 添加 为 secureConnect 事件 的 监听 器 。 
tls.connect() 返回 一 个 tls.TLSSocket 对 象 。 


以 下 是 一 个 上 述 应 签 服务 器 的 客户 端的 例子 : 


var tls = require('tls'); 
var fs = require('fs'); 


var options = { 

// These are necessary only if using the client certificate au 
thentication 

key: fs.readFileSync('client-key.pem'), 

cert: fs.readFileSync('client-cert.pem'), 


// This is necessary only if the server uses the self-signed c 
ertificate 
ca: [ fs.readFileSync('server-cert.pem') | 


P 


var socket = tls.connect(8000, options, function() { 
console.log('client connected’, 
socket.authorized ? 'authorized' : 'unauthorized') 


process.stdin.pipe(socket); 
process.stdin.resume(); 

+); 

socket.setEncoding('utf8'); 

socket.on('data', function(data) { 
console.log(data); 

}); 

socket.on('end', function() { 
server.close(); 


}); 


se 


var tls = require('tls'); 
var fs = require('fs'); 


var options = { 
pfx: fs.readFileSync('client.pfx') 
}; 


var socket = tls.connect(8000, options, function() { 
console.log('client connected’, 
socket.authorized ? 'authorized' : 'unauthorized' ) 


process.stdin.pipe(socket); 
process.stdin.resume(); 


+); 
socket.setEncoding('utf8'); 


socket.on('data', function(data) { 
console.log(data); 


}); 


socket.on('end', function() { 
server.close(); 


}); 


Class: tls. TLSSocket 

net.Socket 实例 的 包装 ， 替 换 了 内 部 socket 的 读 / 写 例 程 ， 来 提供 透明 的 对 
传 入 / 传 出 数据 的 加 密 / 解 密 。 

new tls.TLSSocket(socket, options) 
根据 已 存在 的 TCP socket ， 构 造 一 个 新 的 TLSSocket 4 Ro 

socket 是 一 个 net .Socket 实例 。 

options 是 一 个 可 能 包含 以 下 属性 的 对 象 : 


e secureContext: 一 个 可 选 的 通过 tls.createSecureContext( ... ) 得 到 的 
TLSA BH Ro 


e isServer: 如 果 为 true > TLS socket 将 会 在 服务 器 模式 (server-mode) 
下 被 初始 化 。 


e server: 一 个 可 选 的 net.Server 实例 。 

e requestCert: 可 选 ， 参 阅 tls.createSecurePair 。 

e rejectUnauthorized: 可 选 ， 参 阅 tls.createSecurePair ° 
e NPNProtocols: 可 选 ， 参 阅 tls.createServer ° 

e SNICallback: 可 选 ， 参 阅 tls.createServer 。 

e session: 可 选 ， 一 个 Buffer 实例 ， 包 含 了 TLS 会 话 。 


e requestOCSP: 可 选 ， 如 果 为 true > 0CSP 状态 请 求 扩 展 将 会 被 添加 到 客户 
端 hello， 并 且 OCSPResponse 事件 将 会 在 建立 安全 通信 前 ， 于 socket įk 
发 。 


tls.createSecureContext(details) 
创建 一 个 证 书 对 象 ， details 有 可 选 的 以 下 值 : 


e pfx :一 个 含有 PFX 或 PKCS12 编码 的 私 钥 ， 证 书 和 CA 人 证书 的 字符 串 
或 buffer 。 

e key: 一 个 含有 PEM 编码 的 私 铀 的 字符 囊 。 

e passphrase : 一 个 私 钥 或 pfx 密码 字符 串 。 

e cert: 一 个 含有 PEM 加 密 证 书 的 字符 串 。 

e ca: 一 个 用 来 信任 的 PEM 加 密 CA 证 书 的 字符 串 或 字符 串 列 表 。 

ecrl : 一 个 PEM 加 密 CRL 的 字符 串 或 字符 串 列 表 。 

e ciphers: 一 个 描述 需要 使 用 或 排除 的 加 密 器 的 字符 串 。 更 多 加 密 器 的 格式 细节 

参 
阅 http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FOR 
MAT 。 

e honorCipherOrder : 选择 一 个 加 密 器 时 ， 使 用 使 用 服务 器 的 首选 项 而 不 是 客户 
端的 首选 项 。 默 认为 true 。 更 多 细节 参阅 tls 模块 文档 。 


如 果 没 有 指定 ca ° BA node.js 将 会 使 
用 http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/built 
ins/certdata.txt 提供 的 上 默认 公共 可 信任 CA 列表 。 


tls.createSecurePair([context][, isServer][, requestCert]l, 
rejectUnauthorized]) 


根据 两 个 流 ， 创 建 一 个 新 的 安全 对 (secure pair) 对 象 ， 一 个 是 用 来 读 / 写 加 密 数 
据 ， 另 一 个 是 用 来 读 / 写 明 文 数据 。 通 常 加 密 的 数据 是 从 加 密 数 据 流 被 导 流 而 来 ， 明 
文 数据 被 用 来 作为 初始 加 密 流 的 一 个 百代 。 


e credentials: 一 个 通过 tls.createSecureContext( ... ) 得 到 的 安全 内 容 


对 象 。 


e isServer: 一 个 表明 了 是 否 这 个 tls 连接 应 被 作为 一 个 服务 器 或 一 个 客户 端 打 
开 的 布尔 值 > 


e requestCert: 一 个 表明 了 是 否 服务 器 应 该 向 连接 的 客户 端 请 求证 书 的 布尔 值 。 
只 应 用 于 服务 器 连接 。 


e rejectUnauthorized: 一 个 表明 了 是 否 服务 器 应 该 拒绝 包含 不 可 用 证 书 的 客户 端 
的 布尔 值 。 只 应 用 于 启用 了 requestCert 的 服务 器 。 


tls.createSecurePair() 返回 一 个 带 有 cleartext 和 encrypted ji 属性 的 


对 象 。 


注意 : cleartext 和 tls.TLSSocket 有 相同 的 API ° 


Class: SecurePair 


由 tls.createSecurePair 返回 。 


Event: 'secure' 

当 SecurePair 成 功 建立 一 个 安全 连接 时 ， SecurePair 会 触发 这 个 事件 

与 检查 服务 器 的 secureConnection 事件 相 

似 ，pair.cleartext.authorized 必须 被 检查 ， 来 确认 证 书 是 否 使 用 了 合适 的 
授权 。 

Class: tls.Server 

这 是 一 个 net.Server 的 子 类 ， 并 且 与 其 有 相同 的 方法 。 除 了 只 接受 源 TCP 连 
接 ， 这 个 类 还 接受 通过 TLS 或 SSL 加 密 的 数据 。 

Event: 'secureConnection' 


e function (tlsSocket) {} 


当 一 个 新 连接 被 成 功 握手 后 ， 这 个 事件 会 被 触发 。 参 数 是 一 个 tls.TLssocket 实 
例 。 它 拥有 所 有 普通 流 拥 有 的 事件 和 方法 。 


socket.authorized 是 一 个 表明 了 客户 端 是 否 通过 提供 的 服务 器 CA 来 进行 了 认 
证 的 布尔 值 。 如 果 socket.authorized 为 false > Af 

么 socket.authorizationError 将 被 设置 用 来 描述 授权 失败 的 原因 。 一 个 不 明 
显 的 但 是 值得 提出 的 点 : 依靠 TLS 服 务 器 的 设 定 ， 未 授权 的 连接 可 能 会 被 接 

受 。 socket.npnProtocol 是 一 个 包含 了 被 选择 的 NPN 协 议 的 字符 

串 。 socket.servernam 是 一 个 包含 了 通过 SNI 请 求 的 服务 器 名 的 字符 串 。 


Event: ‘clientError' 
e function (exception, tlsSocket) { } 
当 安 全 连接 被 建立 之 前 ， 服 务 器 触发 了 一 个 error 事件 - 它 会 被 转发 到 这 里 。 


tlsSocket 是 错误 来 自 的 tls.TLSSocket ° 


Event: 'newSession' 


e function (sessionld, sessionData, callback) { } 


在 TLS 会 话 创建 时 触发 。 可 能 会 被 用 来 在 外 部 存储 会 话 。 callback 必须 最 终 被 执 
行 ， 否 则 安全 连接 将 不 会 收 到 数据 。 


注意 : 这 个 事件 监听 器 只 会 影响 到 它 被 添加 之 后 建立 的 连接 。 


Event: 'resumeSession' 


e function (sessionld, callback) {} 


当 客 户 端 想 要 恢复 先前 的 TLS 会 话 时 触发 。 事 件 监听 器 可 能 会 在 外 部 通 

过 sessionId 来 寻找 会 话 ， 并 且 在 结束 后 调用 callback(null, 

sessionData) 。 如 果 会 话 不 能 被 恢复 (例如 没有 找到 ) ， 可 能 会 调 

用 callback(null, null) 。 调 用 callback(err) 会 关闭 将 要 到 来 的 连接 并 且 


销毁 socket 。 


注意 : 这 个 事件 监听 器 只 会 影响 到 它 被 添加 之 后 建立 的 连接 。 


Event: 'OCSPRequest' 


e function (certificate, issuer, callback) { } 


当 客 户 端 发 送 一 个 证 书 状态 请 求 时 触发 。 你 可 以 解释 服务 器 当前 的 证 书 来 获取 
OCSP url 和 证 书 id， 并 且 在 获取 了 OCSP 响 应 后 执行 callback(null, 

resp) ， resp 是 一 个 Buffer 实例 。 certificate 和 issuer 都 是 一 

个 Buffer ， 即 主键 和 发 起 人 证 书 的 DER 代表 (DER-representations) 。 它 们 可 
以 被 用 来 获取 OCSP 证 书 id 和 OCSP 末 端 url。 


另外 ， callback(null, null) 可 以 被 调用 ， 意 味 着 没有 OCSP 响 应 。 
调用 callback(err) ， 将 会 导致 调用 socket.destroy(err) ° 
典型 的 流程 3 


1. 客户 端 连接 到 服务 器 ， 然 后 发 送 一 个 OCSPRequest 给 它 〈 通 
过 ClientHello 中 扩展 的 状态 信息 ) 。 
2. 服务 器 接受 请 求 ， 然 后 执行 OCSPRequest 事件 监听 器 (如 果 存 在 ) © 
3. 服务 器 通过 证 书 或 发 起 人 抓 取 OCSP url， 然 后 向 CA 发 起 一 个 OCSP 请 求 。 
4. 服务 器 从 CA 收 到 一 个 0CSPResponse ， 然 后 通过 回调 函数 的 参数 将 其 返回 给 


sw 
ia ° 


端 验 证 响应 ， 然 后 销毁 socket 或 者 进行 握手 。 


注意 : issuer 可 以 是 null ， 如 果 证 书 是 自 签名 的 或 issuer 不 在 根 证 书 列表 
之 内 (你 可 以 通过 ca 参数 提供 一 个 issuer ) 。 


注意 : 这 个 事件 监听 器 只 会 影响 到 它 被 添加 之 后 建立 的 连接 。 


注意 : 你 可 能 想 要 使 用 一 些 如 asn1.js 的 npm 模块 来 解释 证 书 。 


server.listen(port[, hostname][, callback]) 


从 指定 的 端口 和 主机 名 接收 和 连接。 如 果 hostname 被 忽略 ， 服 务 器 会 在 当 IPv6 可 用 
时 ， 接 受 任 意 IPv6 地 址 ( :: ) 上 的 连接 ， 否 则 为 任意 IPv4 ( 0.0.0.0 ) 上 的 。 
将 port 设置 为 0 则 会 赋予 其 一 个 随机 端口 。 


个 函数 是 异步 的 。 最 后 一 个 参数 callback 会 在 服务 器 被 绑 定 后 执行 。 


ay 


这 
更 多 信息 请 参阅 net.Server 。 


server.close([callback]) 


阻止 服务 器 继续 接收 新 连接 。 这 个 函数 是 异步 的 ， 当 服务 器 触发 一 个 close 事件 
时 ， 服 务 器 将 最 终 被 关闭 。 可 选 的 ， 你 可 以 传递 一 个 回调 函数 来 监听 close 事 
件 。 

server.address() 

返回 绑 定 的 地 址 ， 服 务 器 地 址 的 协议 族 名 和 端口 通过 操作 系统 报告 。 更 多 信息 请 参 
阅 net.Server.address() ° 


server.addContext(hostname, context) 

添加 安全 内 容 ， 它 将 会 在 如 果 客 户 端 请 求 的 SNI 主 机 名 被 传递 的 主机 名 匹配 (可 以 
使 用 通配符 ) 时 使 用 。 context 可 以 包含 密 钥 ， 证 书 ，CA 和 /或 其 他 任 

何 tls.createSecureContext 的 options 参数 的 属性 。 


servermaxConnections 


当 服 务 器 连接 数 变 多 时 ， 设 置 这 个 值 来 拒绝 连接 。 


server.connections 


服务 器 上 的 当前 连接 数 。 


Class: CryptoStream 


稳定 度 : 0 - FF o 使 用 tls.TLSSocket 替代 。 


cryptoStream.bytesWritten 

一 个 底层 socket 的 byteswritten 存 取 器 的 代理 ， 它 会 返回 写 入 socket 的 总 
字 节 数 ， 包 括 TLS 开 销 。 

Class: tls.TLSSocket 


这 是 一 个 net.Socket 的 包装 ， 但 是 对 写 入 的 数据 做 了 透明 的 加 审 ， 并 且 要 求 TLS 
协商 。 


个 实例 实现 了 一 个 双 工 流 接口 。 它 有 所 有 普通 流 所 拥有 的 事件 和 方法 。 


Event: 'secureConnect' 


在 一 个 新 连接 成 功 握手 后 ， 这 个 事件 被 触发 。 无 论 服务 器 的 证 书 被 授权 与 否 ， 这 个 
A 。 测 试 tlsSocket.authorized 来 验证 服务 器 证 书 是 否 被 一 个 

指定 CA 所 签名 取决 于 用 户 。 如 果 tlsSocket.authorized === false 那么 错误 
可 以 从 tlsSocket.authorizationError 里 被 发 现 。 如 果 NPN 被 使 用 ， 你 可 以 
通过 tlsSocket.npnProtocol 来 检查 已 协商 协议 。 


Event: "OCSPResponse' 


e function (response) { } 


yes requestOCSP 选项 被 设置 ， 这 个 事件 会 触发 。 response 是 一 
个 buffer 对 象 ， 包 含 了 服务 器 的 OCSP 响 应 。 


习惯 上 ， response 是 一 个 来 自 服务 器 的 CA (包含 服务 器 的 证 书 撤销 状态 ) 的 已 
签名 对 象 。 

tlsSocket.encrypted 

静态 布尔 变量 ， 总 是 true 。 可 能 会 被 用 来 区 分 TLS socket 和 普通 

的 socket ° 

tlsSocket.authorized 

如 果 对 等 (peer) 证 书 通过 一 个 指定 的 CA 被 签名 ， 那 么 这 个 值 为 true ° SR 
为 false 。 

tlsSocket.authorizationError 

对 等 (peer) 的 证 书 没有 被 验证 的 原因 。 这 个 值 只 在 tlsSocket.authorized === 
false 时 可 用 。 

tlsSocket.getPeerCertificate([ detailed ]) 


返回 了 一 个 代表 了 对 等 证 书 的 对 象 。 返 回 的 对 象 有 一 些 属性 与 证 书 的 属性 一 致 。 如 
果 detailed 参数 被 设置 为 true ， issuer 属性 的 完整 链 都 会 被 返回 ， 如 果 
A false ， 只 返回 不 包含 issuer 属性 的 顶端 的 证 书 。 


例子 : 


{ subject: 
{ €: 7UK', 
ST: 'Acknack Ltd', 
L: "Rhys Jones', 
0: "“node.js', 
OU: 'Test TLS Certificate', 
CN: 'localhost' }, 
issuerInfo: 
人 CU 
ST: “Acknack Ltd’, 
L: "Rhys Jones', 
0: 'node.js', 
OU: 'Test TLS Certificate', 
CN: 'localhost' }, 
issuer: 
{ ... another certificate ... }, 
raw: < RAW DER buffer >, 
valid_from: 'Nov 11 09:52:22 2009 GMT', 
valid_to: 'Nov 6 09:52:22 2029 GMT', 
fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38: 
52:EC:8A:DF', 
serialNumber: 'B9BOD332A1AA5635' } 


如 果 peer 没有 提供 一 个 证 书 ， 那 么 会 返回 null AZAA > 


tlsSocket.getCipher() 
返回 一 个 代表 了 当前 连接 的 加 密 器 名 和 SSL/TLS 协 议 版 本 的 对 象 。 
例子 : { name: 'AES256-SHA', version: 'TLSv1/SSLv3' } 


X http://www.openssl.org/docs/ssl/ssl.html#DEALING WITH_CIPHERS 中 
SSL_CIPHER_get_name() 和 SSL_CIPHER_get_version() ° 


tlsSocket.renegotiate(options, callback) 


初始 化 TLS 重 新 协商 过 程 。 optios 可 以 包含 以 下 属 

性 : rejectUnauthorized > requestCert (详情 参 

阅 tls.createServer ) 。 一 旦 重 协商 成 功 ，callback(err) 会 带 
着 err 为 null 执行 。 


注意 : 可 以 被 用 来 请 求 对 等 (peer) 证 书 在 安全 连接 建立 之 后 。 

另 一 个 注意 点 : 当 作为 服务 器 运行 时 ， socekt 在 handshakeTimeout 超时 后 ， 
会 带 着 一 个 错误 被 销毁 。 

tlsSocket.setMaxSendFragment(size) 


设置 TLS 碎 片 大 小 的 最 大 值 (默认 最 大 值 为 16384 ， 最 小 值 为 512 ) 。 若 设置 成 
功 返回 true ° SMR false 。 


更 小 的 碎片 大 小 来 减少 客户 端的 缓冲 延迟 : ANH A TLSE A? > BANKS 
部 的 碎片 并 且 它 的 完整 性 被 验证 ; 大 碎片 可 能 会 跨越 乡 次 通信 ， 并 且 可 能 会 被 报 文 
丢失 和 重新 排序 所 延迟 。 但 是 ， 更 小 的 碎片 增加 了 额外 的 TLS 框 架 字 节 和 CPU 开 
销 ， 可 能 会 减少 总 体 的 服务 器 负载 。 

tlsSocket.getSession() 

返回 ASN.1 编码 的 TLS 会 话 ， 如 果 没 有 被 协商 ， 返 回 undefined 。 可 以 被 用 在 
重新 连接 服务 器 时 ， 加 速 握手 的 建立 。 

tlsSocket.getTLSTicket() 


注意 : 仅 在 客户 端 TLS socket 中 工作 。 仅 在 调试 时 有 用 ， 因 为 会 话 重新 使 用 了 


给 tls,connect 提供 的 session 选项 。 


返回 TLS 会 话 门票 (ticket) ， 如 果 没 有 被 协商 ， 返 回 undefined ° 


tlsSocket.address() 


返回 绑 定 的 地 址 ， 协 议 族 名 和 端口 由 底层 系统 报告 。 返 回 一 个 含有 三 个 属性 的 对 
象 ， 例 如 : { port: 12346, family: 'IPv4', address: '127.0.0.1' } 。 


tlsSocket.remoteAddress 


代表 了 远程 IP 地 址 的 字符 串 。 例 
子 : '74.125.127.100' 或 '2001:4860:a005::68' ° 


tlsSocket.remoteFamily 

代表 了 远程 IP 协 议 族 的 字符 串 。 'IPv4' 或 'IPv6' © 
tlsSocket.remotePort 

代表 了 远程 端口 数字 。 例 子 : 443 © 
tlsSocket.localAddress 


代表 了 本 地 |IP 地 址 的 字符 串 。 


tlsSocket.localPort 


代表 了 本 地 端口 的 数字 。 


TTY 


Stability: 2 - Stable 
tty 模块 主要 提供 了 tty.ReadStream 和 tty.WriteStream 这 两 个 类 。 大 多 数 
情况 下 ， 你 都 不 需要 直接 使 用 这 个 模块 。 


当 node.js 检测 到 它 运行 于 TTY 上 下 文中 ， 那 么 process.stdin 将 会 是 一 
个 tty.ReadStream 实例 ， process.stdout 将 会 是 一 个 tty.writeStream È 
例 。 测 试 node.js 是 否 运行 在 TTY 上 下 文中 的 一 个 比较 好 的 办 法 是 检 


Æ process.stdout.isTTY 


$ iojs -p -e "Boolean(process.stdout.isTTY)" 


true 
$ iojs -p -e "Boolean(process.stdout.isTTY)" | cat 
false 

tty.isatty(fd) 


如 果 fd 关联 了 终端 ， 就 返回 true ， 反 之 返回 false 。 


tty.setRawMode(mode) 


已 齐 用 。 使 

用 tty.ReadStream#setRawMode() (如 process.stdin.setRawMode() ) 代 
FR o 

日 


Class: ReadStream 


一 个 net .Socket 子 类 ， 代 表 了 一 个 TTY 中 的 可 读 部 分 。 一 般 情 况 下 ， 在 任 
何 node.js 程序 (424 isatty(0) 为 true 时 ) P > process.stdin 将 是 仅 
有 的 tty.ReadStream 实例 。 


rs.isRaw 


一 个 被 初始 化 为 false 的 布尔 值 。 它 代表 了 tty.ReadStream 实例 的 “原始 " 状 
Ae 

rs.setRawMode(mode) 

mode 必须 为 true 或 false 。 它 设 定 tty.ReadStream 的 属性 表现 得 像 原 始 
设备 或 默认 值 。 isRaw 将 会 被 设置 为 结果 模式 (resulting mode) 。 

Class: WriteStream 


一 个 net.Socket 子 类 ， 代 表 了 一 个 TTY 中 的 可 写 部 分 。 一 般 情 况 下 ， 在 任 
何 node.js 程序 ( 仅 当 isatty(1) 为 true 时 ) P > process.stdout 将 是 仅 
有 的 tty.WriteStream 实例 。 


ws.columns 


一 个 表示 了 TTY 当 前 拥有 列 数 的 数字 。 这 个 属性 会 通过 resize 事件 被 更 新 。 


Wws.rows 


一 个 表示 了 TTY 当 前 拥有 行 数 的 数字 。 这 个 属性 会 通过 resize 事件 被 更 新 。 


Event: ‘resize’ 
e function () {} 


当 列 属性 或 行 属性 被 改变 时 ， 通 过 refreshSize() 被 触发 。 


process.stdout.on('resize', function() { 
console.log('screen size has changed!'); 
console.log(process.stdout.columns + 'x' + process.stdout.rows 
); 
}); 


UDP / Datagram Sockets 


稳定 度 : 2 -稳定 
数据 报 socket 通过 require('dgram') 使 用 。 
重要 提示 : dgram.Socket#bind() 的 表现 在 v0.10 中 被 改变 ， 并且 现在 总 是 异步 


的 ， 如 果 你 有 像 这 样 的 代码 : 


var s = dgram.createSocket('udp4'); 
s.bind(1234); 
s.addMembership('224.0.0.114'); 


你 必须 改 成 这 样 : 


var s = dgram.createSocket('udp4'); 
s.bind(1234, function() { 
s.addMembership('224.0.0.114'); 


POD; 


dgram.createSocket(type[, callback]) 


e type String. 'udp4' 或 'udp6' ， 两 者 之 一 
e callback Function. 可 选 ， 会 被 添加 为 message 事件 的 监听 器 
e Returns: socket 3t% 


创建 一 个 指定 类 型 的 数据 报 socket 。 可 用 类 型 是 udp4 和 udp6. 
接受 一 个 可 选 的 回调 函数 ， 它 会 被 自动 添加 为 message 事件 的 监听 器 。 


如 果 你 想 要 接收 数据 报 ， 调 用 socket,bind() ° socket.bind() 将 会 到 所 有 网 
络 接口 地 址 中 的 一 个 随机 端口 (不论 udp4 和 upd6 socket ， 它 都 可 以 正常 工 
Ve) 。 你 可 以 从 socket.address().address 和 socket.address().port 中 获 
取 地 址 和 端口 。 


dgram.createSocket(options[, callback]) 


e options Object 

e callback Function. 会 被 添加 为 message 事件 的 监听 器 

e Returns: socket 对 象 

options 对 象 必 须 包 含 一 个 type 属性， 可 是 udp4 或 udp6。 还 有 一 个 可 选 
的 reuseAddr 布尔 值 属 性 。 


当 reuseAddr 为 true 时 ， socket.bind() 会 重用 地 址 ， 甚 至 是 当 另 一 个 进程 
已 经 在 这 之 上 绑 定 了 一 个 socket "t° RUX false 。 


接受 一 个 可 选 的 回调 函数 ， 它 会 被 自动 添加 为 message 事件 的 监听 器 。 


如 果 你 想 要 接收 数据 报 ， 调 用 socket.bind() ° socket.bind() 将 会 到 所 有 网 
络 接口 地 址 中 的 一 个 随机 端口 (不论 udp4 和 upd6 socket ， 它 都 可 以 正常 工 
Ve) 。 你 可 以 从 socket.address().address 和 socket.address().port FR 
取 地 址 和 端口 。 


Class: dgram.Socket 

dgram. Socket 类 封装 了 数据 报 的 功能 。 它 必须 
被 dgram.createSocket(...) 创建 。 

Event: 'message' 


e msg Buffer object. 消息 
e rinfo Object. 远程 地 址 信息 


当 在 socket 中 一 个 新 的 数据 报 可 用 时 触发 。 msg 是 一 个 buffer 并 
E rinfo 是 一 个 包含 发 送 者 地 址 信息 的 对 象 : 


socket.on('message', function(msg, rinfo) { 
console.log('Received %d bytes from %s:%d\n', 
msg.length, rinfo.address, rinfo.port); 


+); 


Event: ‘listening’ 


当 一 个 socket 开始 监听 数据 报时 触发 。 在 UDP socket 被 创建 时 触发 。 


Event: ‘close’ 


在 一 个 socket 通过 close() 被 关闭 时 触发 。 这 个 socket 中 不 会 再 触发 新 
的 message 事件 。 


Event: ‘error' 
e exception Error object 


当 错 误 发 生 时 触发 。 


socket.send(buf, offset, length, port, address[, callback]) 


e buf Buffer object or string. 要 被 发 送 的 信息 。 

e offset Integer. 信息 在 buffer 里 的 初始 偏 移 位 置 。 
e length Integer. 信息 的 字 节 数 。 

e port Integer. 目标 端口 。 

e address String. 目标 主机 或 I|P 地 址 。 

e callback Function. 可 选 ， 当 信息 被 发 送 后 调用 。 


对 于 UDP socket ， 目 标 端口 和 地 址 都 必须 被 指定 。 address 参数 需要 提供 一 
个 字符 串 ， 并 且 它 会 被 DNS 解析 。 


如 果 address 被 忽略 ， 或 者 是 一 个 空 字符 串 。 将 会 使 用 '0.0.0.0' 或 '::0' © 
这 取决 于 网 络 配置 ， 这 些 默 认 值 可 能 会 或 可 能 不 会 正常 工作 ; 所 以 最 好 还 是 明确 
指定 目标 地 址 。 

如 果 一 个 socket 先前 没有 被 调用 bind 来 绑 定 ， 它 将 会 赋 于 一 个 随机 端口 数 并 

且 被 绑 定 到 “所 有 网 络 接口 "地 址 (udp4 socket 为 '0.0.0.0' ，udp6 则 

为 '::0' ) œ 

一 个 可 选 的 回调 函数 可 以 被 指定 ， 用 来 检测 DNS 错误 ， 或 决定 重用 buf 对 象 是 否 
安全 。 注 意 ，DNS 查 找 至 少 会 延迟 一 个 事件 循环 。 唯 一 能 确定 数据 报 被 发 送 的 方法 
就 是 使 用 一 个 回调 函数 。 

出 于 对 多 字 节 字符 的 考虑 ， offset 和 length 将 会 根据 字 节 长 度 而 不 是 字符 位 

置 被 计算 。 


一 个 向 localhost 上 的 一 个 随机 端口 发 送 UDP 报 文 的 例子 : 


var dgram = require('dgram'); 
var message = new Buffer("Some bytes"); 
var client = dgram.createSocket("udp4"); 
client.send(message, 0, message.length, 41234, "localhost", func 
tion(err) { 
client.close(); 


+); 


UDP 数据 报 大 小 的 注意 事项 


IPv4/v6 数 据 报 的 最 大 大 小 取决 于 MTU (最 大 传输 单位 ) ， 和 Payload 
Length 字段 大 小 。 


e Payload Length 是 16 字 节 宽 的 ， 意 味 着 一 个 正常 的 负载 不 能 超过 64K 入 位 
字 节 ， 包 括 网 络 头 和 数据 (65,507 字 节 = 65,535 - 8 字 节 UDP K-20 FF 
IP 头 ) ; 对 于 环 回 接口 总 是 true ， 但 是 如 此 大 的 数据 报 对 于 大 多 数 主 机 和 
网 络 来 说 都 是 不 现实 的 。 


e。 MTU 是 指定 的 链 路 层 技术 支持 的 报 文 的 最 大 大 小 。 对 于 所 有 连接 ，IPv4 人 允许 
最 小 MTU 为 68 入 位 字 节 ， 而 推荐 的 IPv4 MTU 是 576 (通常 作为 拨号 类 应 用 的 
推荐 MTU ) ， 无 论 它们 是 完整 的 还 是 以 碎片 形式 到 达 。 


e 对 于 IPv6， 有 最 小 MTU 是 1280 入 位 字 节 ， 人 但是， 允许 的 最 小 buffer 重组 大 小 
是 1500 入 位 字 节 。68 人 入 位 字 节 非常 小 ， 所 以 大 多 数 的 当前 链 路 层 技术 的 最 
‘ MTU 都 是 1500 (如 Ethernet ) ° 


注意 ， 不 可 能 提前 知道 一 个 报 文 可 能 经 过 的 每 一 个 连接 MTU ， 并 且 通 常 不 能 发 送 
一 个 大 于 (接收 者 ) MTU 的 数据 报 ( 报 文 会 被 默默 丢弃 ， 不 会 通知 源头 : 这 个 数 
据 没 有 到 达 已 定 的 接收 方 ) 。 


socket.bind(port[, address][, callback]) 


e port Integer 
e address String, 可 选 
e callback Function 可 选 ， 没 有 参数 。 当 绑 定 完毕 后 触发 。 


对 于 UDP socket ， 监 听 一 个 具名 的 端口 和 一 个 可 选 的 地 址 上 的 数据 报 。 如 
果 address 没有 被 指定 ， 操 作 系 统 将 会 试图 监听 所 有 端口 。 在 绑 定 完毕 
后 ， listening 事件 会 被 吃 法 ， 并 且 回 调 函 数 (如 果 指 定 了 ) 会 被 调用 。 同 时 指 


定 listening 事件 的 监听 器 和 callback 没有 危险 ， 但 是 不 是 很 有 用 。 
一 个 绑 定 的 数据 报 socket 将 会 保持 node.js 进程 的 运行 ， 来 接受 数据 报 。 


如 果 绑 定 失 败 ， 一 个 error 事件 会 产生 。 极 少数 情况 下 (例如 绑 定 一 个 关闭 
的 socket ) ， 这 个 方法 会 抛 出 一 个 错误 。 


一 个 监听 41234 端 口 的 UDP 服 务 器 : 


var dgram = require("dgram"); 
var server = dgram.createSocket("udp4"); 


server.on("error", function (err) { 
console.log("server error:\n" + err.stack); 
server .close(); 


PO 


server.on("message", function (msg, rinfo) { 
console.log("server got: " + msg + " from ”十 
rinfo.address + ":" + rinfo.port); 


+); 


server.on("listening", function () { 
var address = server.address(); 
console.log("server listening " + 
address.address + ":" + address.port); 


}); 


server .bind(41234); 
// server listening 0.0.0.0:41234 


socket.bind(options[, callback]) 


e options Object - 必 选 ， 支 持 以 下 属性 : 
o port Number - 必须 
o address String - 可 选 
o exclusive Boolean - 可 选 

e callback Function - 可 选 


options 的 prot 和 address 属性 ， 以 及 可 选 的 回调 函数 ， 
与 socket.bind(port, [address], [callback]) 中 它们 的 表现 一 致 。 


如 exclusive A false (Rik) ， 那 么 集群 的 工作 进程 将 会 使 用 相同 的 底层 句 
柄 ， 人 允许 共享 处 理 连 接 的 职责 。 当 为 true 时 ， 句 杨 不 被 共享 ， 企 图 共享 端口 会 导 
致 一 个 错误 。 一 个 监听 一 个 exclusive 端口 的 例子 : 


socket.bind({ 
address: 'localhost', 
port: 8000, 
exclusive: true 


}); 


socket.close([callback]) 
关闭 底层 socket ， 并 且 停 止 监听 新 数据 。 如 果 提 供 了 回调 函数 ， 它 会 被 添加 
为 close 事件 的 监听 器 。 
socket.address() 
返回 一 个 包含 socket 地 址 信息 的 对 象 。 对 于 UDP socket ， 这 个 对 象 将 会 包 
含 address > family 和 port 。 
socket.setBroadcast(flag) 
e flag Boolean 
设 ay 除 SO_BROADCAST socket 设置 。 当 这 个 选项 被 设置 ，UDP 报 文 将 会 被 
送 至 
送 至 


本 地 接口 的 广播 地 址 。 


socket.setTTL(ttl) 


e ttl Integer 


设置 IP_TTL socket 选项 。 TIL 的 意思 是 “生存 时 间 (TimetoLive) ”， 但 是 
在 这 里 的 上 下 文中 ， 它 值 一 个 报 文通 过 的 |P 跃 点 数 。 每 转发 报 文 的 路 由 或 网 关 都 会 
递减 TTL 。 如 果 TIL 被 一 个 路 由 递减 为 0 ， 它 将 不 再 被 转发 。 改 变 TTL 值 常 
用 于 网 络 探 测 器 或 多 播 。 


setTTL() 的 参数 是 一 个 1 到 225 之 间 的 跃 点 数 。 多 数 系统 中 的 默认 值 
为 64 。 


socket.setMulticastTTL(ttl) 


e ttl Integer 


设置 IP_MULTICAST_TTL socket 选项 。 TIL 的 意思 是 “生存 时 间 (Time to 
Live) ”， 但 是 在 这 里 的 上 下 文中 ， 它 值 一 个 报 文通 过 的 |P 跃 点数， 特别 是 组 播 流 
量 。 每 转发 报 文 的 路 由 或 网 关 都 会 递减 TTL 。 如 果 TIL 被 一 个 路 由 递减 为 0 ， 
它 将 不 再 被 转发 。 


setMulticastTTL() 的 参数 是 一 个 6 到 225 之 间 的 跃 点 数 。 多 数 系 统 中 的 默认 
值 为 1 。 
socket.setMulticastLoopback(flag) 

e flag Boolean 
设置 或 清除 IP_MULTICAST_LOOP socket 选项 。 当 这 个 选项 被 设置 ， 组 播报 文 
也 将 会 在 本 地 接口 上 接收 。 
socket.addMembership(multicastAddress[， 


multicastinterface]) 


e multicastAddress String 
e multicastInterface String, 可 选 


告诉 内 核 加 入 一 个 组 播 分 组 ， 通 过 IP_ADD MEMBERSHIP socket 选项 。 

如 果 multicastInterface 没有 被 指定 ， 那 么 操作 系统 将 会 尝试 加 入 成 为 所 有 可 
用 的 接口 的 成 员 。 

socket.dropMembership(multicastAddress|， 


multicastinterface]) 


e multicastAddress String 
e multicastInterface String, 可 选 


与 addMembership 相反 -告诉 内 核 离开 一 个 组 播 分 组 ， 通 
过 IP_DROP_MEMBERSHIP socket 选项 。 当 socket 被 关闭 或 进程 结束 时 ， 它 
会 被 内 核 自 动 调用 。 所 以 大 多 数 应 用 不 需要 亲自 调用 它 。 


如 果 multicastInterface 没有 被 指定 ， 那 么 操作 系统 将 会 尝试 脱离 所 有 可 用 的 
接口 。 
socket.unref() 


在 一 个 socket 上 调用 unref 将 会 在 它 是 事件 系统 中 唯一 活跃 的 socket He A 
许 程序 退出 。 如 果 socket 已 经 被 unref ， 再 次 调用 将 不 会 有 任何 效果 。 


返回 一 个 socket 。 


socket.ref() 


与 unref 相反 ， 在 一 个 先前 被 unref 的 socket 上 调用 ref ， 那 么 在 它 是 唯一 
的 剩余 的 socket (RUITA) 时 ， 将 不 允许 程序 退出 。 如 果 socket 已 经 
被 ref ， 再 次 调用 将 不 会 有 任何 效果 。 


返回 一 个 socket 。 


URL 


稳定 度 : 2 -稳定 
这 个 模块 提供 了 URL 解 析 和 解释 的 工具 。 通 过 require('url') 使 用 它 。 


解释 URL 为 一 个 人 金 有 以 下 部 分 或 全 部 属性 的 对 象 ， 依 赖 于 它们 是 否 在 URL 字 符 串 中 
存在 。 任 何不 存在 的 部 分 都 不 会 出 现在 解释 后 的 对 象 中 。 一 个 下 面 URL 的 例子 : 


"http://user :pass@host.com:8080/p/a/t/h?query=string#hash' 
o href: 最 初 传递 的 全 部 URL。 协 议和 主机 都 是 小 写 的 。 
例子 : '‘http://user:pass@host .com:8080/p/a/t/h?query=string#hash ' 
e protocol: 请 求 的 协议 ， 小 写 。 
例子 : Behe 
e slashes: 协议 要 求 冒 号 后 有 斜 杠 。 
例子 : true 或 false 
e host: URL 的 所 有 主机 部 分 ， 包 括 端口 ， 小 写 。 
例子 : "host.com:8080' 
e auth: URL 的 认证 信息 部 分 。 
例子 : 'user:pass' 
e hostname: 小 写 的 主机 名 部 分 。 
例子 : 'host.com' 
© port: 主机 部 分 的 端口 号 。 
例子 : '8080' 


e pathname: URL 的 路 径 部 分 ， 在 主机 之 后 ， 在 查询 之 前 ， 包 括 最 前 面 的 斜 杠 ， 
如 果 存 在 的 话 。 不 提供 解码 。 


例子 :  '/p/a/t/h' 


e search: URL 的 “查询 字符 串 ” 部 分 ， 包 括 前 导 的 问号 标志 。 
例子 : '?query=string' 
o path: 路 径 和 查询 的 连接 体 。 不 提供 解码 。 
例子 : '/p/a/t/h?query=string' 
e query: 查询 字符 串 的 “参数 "部 分 ， 或 查询 字符 串 被 解释 后 的 对 象 。 
例子 : 'query=string' 或 {'query':'string'} 
e hash: URL 的 “碎片 "部 分 ， 包 括 英镑 符号 。 
例子 : '#hash' 


以 下 是 URL 模 块 提供 的 方法 : 


url.parse(urlStr[, parseQueryString][, slashesDenoteHost]) 
接收 一 个 URL 字 符 串 ， 然 后 返回 一 个 对 象 。 


对 第 二 个 参数 传递 true ， 将 使 用 querystring 模块 来 解释 查询 字符 串 。 如 果 
为 true ， 那 么 最 后 的 对 象 中 一 定 存 在 query 属性 ， 并 且 search 属性 将 总 是 一 
个 字符 串 (可 能 为 空 ) 。 如 果 为 false ， 那 么 query 属性 将 不 会 被 解释 或 解 

码 。 软 认为 false 。 


上 大 大 ”一 


对 第 三 个 参数 传递 true ， 将 会 把 //foo/bar 解释 为 { host: 'foo', 
pathname: '/bar' } ， 而 不 是 { pathname: '//foo/bar' } ° RU 
A false 。 


url.format(urlObj) 
接受 一 个 解释 完毕 的 URL 对 象 ， 返 回 格式 化 URL 字 符 串 。 


以 下 是 格式 化 过 


程 : 


+ 
e href 将 会 被 忽略 。 
。 path 将 会 被 忽略 。 
。 协议 无 论 是 否 有 末尾 的 冒号 ， 都 会 被 同样 处 理 。 
o http > https > ftp > gopher > file 协 议 的 后 级 是 :// 。 
o 所 有 其 他 如 mailto，xmpp，aim，sftp，foo 等 协议 的 后 组 是 : 。 


o 如 果 协 议 要 求 有 :// ， slashes 会 被 设置 为 true 
o 只 有 之 前 没有 列 出 的 要 求 有 斜 线 的 协议 才 需 要 被 设置 。 
如 mongodb://localhost:8000/ ° 
e auth 会 被 使 用 ， 如 果 存 在 的 话 。 
© 只 有 当 缺 少 host 时 ， 才 会 使 用 hostname ° 
e RKA ZY host 时 ， 才 会 使 用 port ° 
e host 将 会 替代 hostname 和 port ° 
© 无 论 有 没有 前 导 / (A) > pathname 都 会 被 相同 对 待 。 
e@ 只 有 在 缺少 search 时 ， 才 会 使 用 query (2 : 参阅 querystring ) ° 
e search 将 会 替代 query 
o 无 论 有 没有 前 导 ?3 ( 问 
e LARA SH ( 美 镑 符 


号 ) ， 它 都 会 被 相同 对 待 。 
号 ) > hash 都 会 被 相同 对 待 。 


url.resolve(from, to) 


接受 一 个 基础 URL， 和 一 个 路 径 URL， 并 且 带 上 锚 点 像 浏览 器 一 样 解 析 他 们 。 例 
Fi 


url.resolve('/one/two/three', 'four') // ‘/one/two/four ' 
url.resolve('http://example.com/', '/one') // ‘http://example 
.com/one' 
url.resolve('http://example.com/one', '/two') // 'http://example 
.com/two' 


util 


稳定 度 : 2 -稳定 
些 功 能 在 模块 'util' 中 ， 通 过 require('util') 来 使 用 它们 。 


util 模块 主要 的 设计 意图 是 满足 node.js 内 部 API 的 需要 。 但 是 许多 工具 对 于 
你 的 程序 也 十 分 有 用 。 如 果 你 发 现 这 些 功能 不 能 满足 你 的 需要 ， 那 么 鼓励 你 编写 自 
己 的 工具 集 。 我 们 对 任何 node.js 内 部 功能 不 需要 的 功能 ， 都 不 感 兴趣 。 


util.callbackify(original) 


于 V8.2.0 加 入 


e original async 函数 
e Returns: 回调 函数 


参数 接收 一 个 async 元 数 ( 或 者 函数 返回 值 是 promise ), 返回 一 个 Node.js 错 误 优 
先 的 回调 函数 , 第 一 个 参数 是 错误 原因 (如 果 Promise 处 于 resolve , 则 返 
回 null ), 第 二 个 参数 返回 结果 


例子 
const util = require('util'); 


async function fn() { 
return await Promise.resolve('hello world'); 


} 


const callbackFunction = util.callbackify(fn); 


callbackFunction((err, ret) => { 
if (err) throw err; 
console.log(ret); 


}); 


hello world 


备注 : 
e callback 是 异步 执行 的 ， 并 且 会 有 一 个 有 限 的 堆栈 跟踪 。 如 
Æ callback 抛 出 ， 进 程 将 发 出 uncaughtException 事件 ， 如 果 不 处 理 则 
退出 。 
e 由 于 null 具有 作为 回调 的 第 一 个 参数 的 特殊 含义 ， 因 此 如 果 外 层 泡 数 拒绝 带 
有 虚假 值 的 Promise 作为 原因 ( reason )， 则 该 值 将 被 包装 在 Error 中 ， 初 识 
值 将 存储 在 名 为 reason 的 字段 中 。 
util.debuglog(section) 
于 v0.11.3 加 入 


e section String 需要 被 调试 的 程序 节点 
e Returns: Function A & 2b 32 % 4% 


这 个 方法 被 用 来 在 NODE DEBUG 环境 变量 存在 的 情况 下 ， 创 cL, 
A stderr 的 函数 。 如 果 section 名 出 现在 环境 变量 中 ， 那 么 返回 的 函数 
与 console.error() Rte SR > RAF HR o 


例子 : 
var debuglog = util.debuglog('foo'); 


var bar = 123; 
debuglog('hello from foo [%d]', bar); 


如 果 程 序 在 NODE_DEBUG=foo 环境 下 运行 ， 那 么 输出 将 是 : 
FOO 3245: hello from foo [123] 


3245 是 进程 jd。 如果 这 个 环境 变量 没有 设置 ， 那 么 将 不 会 打印 任何 东西 。 


你 可 以 通过 去 号 设置 多 个 NODE DEBUG 环境 变量 。 例 
如 ， NODE_DEBUG=fs,net,tls 。 


util.deprecate(function, string) 


于 v0.8.0 加 入 util.deprecate () 方法 包装 给 定 的 函数 或 类 ， 使 其 被 标记 为 


CHM 。 
const util = require( util’); 


exports.puts = util.deprecate(function() { 
for (let i = 0, len = arguments.length; i < len; ++i) { 
process.stdout.write(arguments[i] + '\n'); 


} 


}, ‘util.puts: Use console.log instead'); 


当 被 调用 时 ，util.deprecate () 将 返回 一 个 函数 ， 该 函数 将 调 

用 process.on ('warning') 事件 发 出 一 个 Deprecationwarning 敬告。 默认 
情况 下 ， 第 一 次 被 调用 时 ， 这 个 警告 将 被 发 射 并 打印 到 stderr 。 发 出 警告 后 ， 
将 调用 包装 函数 。 

如 果 --no-deprecation 或 --no-warnings 其 中 一 个 命令 行 标 记 被 使 用 ， 或 者 
在 第 一 个 弃 用 警告 之 前 将 process .noDeprecation 属性 设置 为 true ， 那 

A util.deprecate () 方法 将 不 执行 任何 操作 。 


pi --trace-deprecation 或 --trace-warnings 其 中 一 个 命令 行 标记 被 设 
， 或 者 将 process.noDeprecation 属性 设置 为 true ， 当 第 一 次 调 
用 deprecated 方法 时 ， 会 打印 一 个 警告 或 者 对 战 信息 到 stderr 中 。 


如 果 --trace-deprecation 命令 被 设置 ， 或 者 将 process.noDeprecation & 
性 设置 为 true ， 在 第 一 次 调用 deprecated 方法 时 将 会 抛 出 异常 


-throw-deprecation 命令 行 标记 和 process.throwDeprecation 属性 优先 于 
--trace-depreation 和 process.traceDeprecation 。 
util.format(format[, ...]) 

使 用 第 一 个 参数 ， 像 printf 一 样 的 格式 输出 格式 化 字符 串 。 


第 一 个 参数 是 一 个 包含 了 0 个 或 更 多 占 位 符 的 字符 串 。 每 个 占 位 符 都 被 其 后 的 参数 
所 替换 。 支 持 的 占 位 符 有 : 


e %S- FiF 


e Hd - 数字 (整数 和 浮 点 数 ) 

e %i- 整 型 

e $o- 对 象 。 是 javascripts 通用 对 象 的 一 种 字符 串 表 现形 式 。 
与 util.inspect() 设置 { showHidden: true, depth: 4, showProxy: 
true } 类 似 。 将 显示 完成 的 对 象 ， 但 不 包括 不 可 枚 举 的 符号 和 属性 。 

e 9$O - 对 象 。 是 javascripts 通用 对 象 的 一 种 字符 串 表 现形 式 。 
与 util.inspect() 不 设置 任何 选项 类 似 。 将 显示 完成 的 对 象 ， 但 不 包括 不 
可 枚 举 的 符号 和 属性 。 

e %j- JSON。 如 果 参 数 包含 循环 引用 ， 则 返回 字符 串 '[Circular]' ° 

e %% - 单独 的 百分比 符号 ( '%' ) ， 它 不 消耗 一 个 参数 。 


如 果 占 位 符 没有 对 应 的 参数 ， 那 么 占 位 符 将 不 被 蔡 换 。 


util.format('%s:%s', 'foo'); // 'foo:%s' 


如 果 参 数 多 余 占 位 符 ， 那 么 额外 的 参数 会 被 转换 成 字符 串 〈 对 于 对 象 和 链接 ， 使 
用 util.inspect() ) ， 并 且 以 空格 连接 。 


util.format('%s:%s', ‘foo’, 'bar', 'baz'); // 'foo:bar baz ' 


如 果 第 一 个 参数 不 是 格式 化 字符 串 ， 那 么 util. format() 将 会 返回 一 个 以 空格 连 
接 的 所 有 参数 的 字符 串 。 每 一 个 参数 都 被 调用 util.inspect() 来 转换 成 字符 
串 。 


Util rornak(t. 2.3) 77 1 233) 


util.inherits(constructor, superConstructor) 


e 历史 
o v5.0.0 构造 了 兄 数 现在 可 以 使 用 ES6 中 的 类 
o v0.3.0 被 添加 


备注 : 不 鼓励 使 用 util.inherits() 。 请 使 用 ES6 类 并 扩展 关键 字 以 获得 语言 级 
别 的 继承 支持 。 另 请 注意 ， 这 两 种 风格 在 语义 上 是 不 兼容 的 。 


e constructor 


e superConstructor 


将 原型 方法 从 一 个 构造 函数 继承 到 另 一 个 构造 函数 。 构造 函数 的 原型 将 被 设置 为 由 
超级 构造 函数 创建 的 新 对 输 。 


作为 一 种 额外 的 便捷 使 用 方法 ， superConstructor 将 可 以 使 


用 constructor.super_ property 访问 。 


const util = require('util'); 
const EventEmitter = require('events'); 


function MyStream() { 
EventEmitter.call(this); 


util.inherits(MyStream, EventEmitter); 


MyStream.prototype.write = function(data) { 
this.emit('data', data); 


}; 
const stream = new MyStream(); 


console.log(stream instanceof EventEmitter); // true 
console.log(MyStream.super_ === EventEmitter); // true 


stream.on('data', (data) => { 
console.log( Received data: "${data}"~); 


}); 


stream.write('It works!'); // Received data: "It works!" 


在 ES6 中 使 用 类 和 继承 


const EventEmitter = require('events'); 


class MyStream extends EventEmitter { 
write(data) { 
this.emit('data', data); 


const stream = new MyStream(); 


stream.on('data', (data) => { 
console.log( Received data: "S${data}""); 


}); 
stream.write('With ES6'); 


util.log(string) 
Eih E Fat h A A AT ARGA D o 


require('util').log('Timestamped message.'); 


util.inspect(object[, options]) 
返回 一 个 代表 了 object 的 字符 串 ， 在 调试 时 很 有 用 。 
一 个 可 选 的 options 对 象 可 以 被 传递 以 下 属性 来 影响 字符 串 的 格式 : 


e ShowHidden - 如 果 设 置 为 true ， 那 么 对 象 的 不 可 枚 举 属 性 也 会 被 显示 。 默 
认为 false 。 


e depth - 告诉 inspect 格式 化 对 象 时 需要 递归 的 次 数 。 这 对 于 巨大 的 复杂 对 象 
十 分 有 用 。 默 认为 2 。 传 递 null 表示 无 限 递归 。 


e Colors - 如 果 为 true ， 那 么 输出 会 带 有 ANSI 颜 色 代 码 风 格 。 默 认 
A false 。 闫 色 是 可 以 自 定 义 的 ， 参 阅 下 文 。 


e customlnspect - 如 果 为 false ， 那 么 定义 在 被 检查 对 象 上 
的 inspect(depth, opts) 有 函数 将 不 会 被 调用 。 默 认为 false 。 


一 个 检查 util 对 象 所 有 属性 的 例子 : 
Var util = requare( Util’); 


console. log(util.inspect(util, { showHidden: true, depth: null } 
)); 


参数 值 可 以 提供 了 它们 自己 的 inspect(depth, opts) 函数 ， 当 被 调用 时 它们 会 
收 到 当前 的 递归 深度 值 ， 以 及 其 他 传递 给 util.inspect() 的 选项 。 


自 定义 util.inspect 颜色 


util.inspect 的 有 颜色 的 输出 〈 如 果 司 用 ) 可 以 全 局 的 通 
过 util.inspect.styles 和 util.inspect.colors 对 象 来 自 定 义 。 


util.inspect.styles 是 通过 util.inspect.colors 设置 每 个 风格 一 个 颜色 的 
映射 。 高 亮 风格 和 它们 的 默认 值 为 number (yellow) boolean (yellow) string 
(green) date (magenta) regexp (red) null (bold) undefined (grey) 
special 。 这 时 的 唯一 方法 (cyan)* name (intentionally no styling) ° 


Fle LH BA white, grey, black, blue, cyan, green, magenta, red 和 
yellow 。 他 们 都 是 bold ， italic ， underline 和 inverse 代码 。 


自 定 义 对 象 的 inspect() BA 


对 象 也 可 以 自己 定义 inspect(depth) HÆ > util.inspect() 将 会 调用 它 ， 并 
且 输 出 它 的 结果 : 


var util = require('util'); 


var obj = { name: 'nate' }; 
obj.inspect = function(depth) { 
return '{' + this.name + '}'; 


ia 


util.inspect(obj); 
if ace) 


你 也 可 以 完全 返回 另 一 个 对 象 ， 并 且 返 回 的 字符 串 是 由 这 个 返回 对 象 格式 化 而 来 
的 ， 这 也 JSON.stringify() 相似 : 


var obj = { foo: 'this will not show up in the inspect() output' 
}; 

obj.inspect = function(depth) { 
return { bar: 'baz' }; 


P 


util.inspect(obj); 
J {Dale oazi pi 


util.inspect.custom 
添加 : v6.6.0 可 用 于 声明 定制 检查 功能 的 符号 ， 可 以 参考 Custom inspection 
functions on Objects 

util.inspect.defaultOptions 
添加 : v6.4.0 


defaultOptions 允许 自 定义 util.inspect 的 默认 选项 。 这 对 于 

4% console.log 或 util.format 这 样 的 函数 是 非常 有 用 的 ， 它 隐 式 地 调 

用 util.inspect ° 它 应 被 设置 为 包含 一 个 或 多 个 有 效 的 util.inspect() 选项 
的 对 象 。 当然 直接 设置 选项 属性 也 被 支持 的 。 


const util = require('util'); 
const arr = Array(101).f1i11(0); 


console.log(arr); // 打印 被 截取 过 后 的 数组 
util.inspect.defaultOptions.maxArrayLength = null; 
console.log(arr); // 打印 整个 数组 


util.promisify(original) 
V8.0.0 加 入 


e original 


e Returns 


把 Node.js 的 回调 风格 ， 即 (err > value) => ... 作为 最 后 一 个 参数 ， 并 返回 一 


个 promise ° 
举例 : 


const util = require('util'); 
const fs = require('fs'); 


const stat = util.promisify(fs.stat); 
stat('.').then((stats) => { 

// Do something with “stats” 
}).catch((error) => { 

// Handle the error. 


DD; 


或 者 使 用 async : 


const util = require('util’); 
const fs = require('fs'); 


const stat = util.promisify(fs.stat); 


async function callStat() { 
const stats = await stat('.'); 
console.log( This directory is owned by ${stats.uid}); 


如 果 存 在 原生 的 [util.promisify.custom] 属性 ， promisify 会 返回 执行 后 的 
结果 ， 可 以 参考 Custom promisified functions ° 


基本 所 有 情况 下 ， promisify() 方法 都 会 假设 original 是 将 回调 函数 作为 最 后 
一 个 参数 传 入 ， 如 果 不 是 ， 则 返回 undefined 。 
自 定 义 promisified 4 %& 


使 用 util.promisify.custom 符号 可 以 覆盖 util.promisify() 的 返回 值 : 


const util = require('util’); 


function doSomething(foo, callback) { 
tf 


doSomething[util.promisify.custom] = function(foo) { 
return getPromiseSomehow(); 


ia 


const promisified = util.promisify(doSomething) ; 
console.log(promisified === doSomething[util.promisify.custom] ); 
// prints 'true' 

这 对 于 源 函 数 不 遵 循 将 错误 优先 回调 作为 最 后 一 个 参数 的 标准 格式 的 情况 很 有 用 。 


例如 ， 这 样 一 个 函数 (food，onSuccess Callback’ onError Callback) : 


doSomething[util.promisify.custom] = function(foo) { 
return new Promise(function(resolve, reject) { 
doSomething(foo, resolve, reject); 
+); 
}; 


util.promisify.custom 
V8.0.0 添 加 


可 用 于 声明 函数 的 自 定义 promisified 变 体 的 符号 ， 参 考 Custom promisified 
functions ° 


Class: util. TextDecoder 


V8.3.0 添 加 一 种 WHATWG 编 码 标准 TextDecoder API 的 实现 。 


const decoder = new TextDecoder('shift_jis'); 
let string = ''; 
let buffer; 
while (buffer = getNextChunkSomehow()) { 
string += decoder.decode(buffer, { stream: true }); 


} 


string += decoder.decode(); // end-of-stream 


Ve F 47-4 API 
以 下 API 已 被 弃 用 ， 不 应 再 使 用 。 应 该 更 新 现 有 的 应 用 程序 和 模块 以 寻找 替代 方 
法 。 
util._extend(target, source) 
Vv0.7.5 添 加 Vv6.0.0 废 弃 稳定 度 : 0 - 弃 用 : 用 Object.assign() RË. 


util._extend() 本 来 不 打算 在 内 部 Node.js 模 块 之 外 使 用 。 是 社区 的 人 找到 他 随 
意 使 用 的 。 


它 已 被 弃 用 ， 不 应 在 新 代码 中 使 用 。 JavaScript 通过 Object.assign() 提供 
了 非常 类 似 的 内 置 功能 。 
util.isArray(object) 
稳定 度 : 0 - 弃 用 
Array.isArray 的 内 部 别名 。 


如 果 object 是 一 个 数组 则 返回 true > SMR false ° 


var util = require('util'); 


util.isArray([]) 

// true 
util.isArray(new Array) 

7// true 
util.isArray({}) 

// false 


util.isRegExp(object) 
稳定 度 : 0 - HA 


如 果 object 是 一 个 正则 表达 式 则 返回 true > SMI false 。 


var util = require('util'); 


util.isRegExp(/some regexp/) 
// true 

util.isRegExp(new RegExp('another regexp' ) ) 
// true 

util.isRegExp({}) 
// false 


util.isDate(object) 


如 果 object 是 一 个 日 期 则 返回 true > SMA false 。 
var util = require('util'); 


util.isDate(new Date()) 

// true 
util.isDate(Date()) 

// false (without 'new' returns a String) 
util.isDate({}) 

// false 


util.isError(object) 
稳定 度 : 0 - 弃 用 

如 果 object 是 一 个 错误 对 象 则 返回 true > SMA false 。 
var util = require('util'); 


util.isError(new Error()) 


Mi true 

util.isError(new TypeError()) 
// true 

util.isError({ name: 'Error', message: 'an error occurred' }) 
/7 false 


util.isBoolean(object) 
稳定 度 : 0 - 弃 用 


如 果 object 是 一 个 布尔 值 则 返回 true > GIAE false ° 
var util = require('util'); 


util.isBoolean(1) 

// false 
util.isBoolean(0) 

// Talse 
util.isBoolean( false) 

/7 true 


util.isNull(object) 


~ 


稳定 度 : 0 - 弃 用 


¢ 


如 果 object 是 严格 的 null 则 返回 true > GUAE false 。 


var util = require('util'); 


util.isNull(0) 

// Talse 
util.isNull(undefined) 

// Talse 
util.isNull(null) 

// true 


util.isNullOrUndefined(object) 
稳定 度 : 0 - 弃 用 


如 果 object 是 一 null 或 undefined 则 返回 true ， 和 否则 返回 false ° 
var util = require('util'); 


util.isNull0rUndefined (0) 

// Talse 
util.isNullOrUndefined(undefined) 

// true 
util.isNull0OrUndefined(null) 

// true 


util.isNumber(object) 
稳定 度 : 0 - 弃 用 


如 果 object 是 一 个 数字 则 返回 true > GIAE false 。 


var util = require('util'); 


util.isNumber (false) 
// Talse 
util.isNumber (Infinity) 
7/ true 
util.isNumber (0) 
// true 
util.isNumber (NaN) 
/7 true 


util.isString(object) 
稳定 度 : 0 - 弃 用 


如 果 object 是 一 个 字符 串 则 返回 true > GIAE false ° 
var util = require('util'); 


util.isString('') 
// true 
util.isString('foo') 
// true 
util.isString(String('foo')) 
// true 
util.isString(5) 
// false 


util.isSymbol(object) 
稳定 度 : 0 - 弃 用 


如 果 object 是 一 个 Symbol 则 返回 true > SMA false 。 


var util = require('util'); 


util.isSymbol(5) 

// Talse 
util.isSymbol('foo') 

// false 
util.isSymbol(Symbol('foo')) 

// true 


util.isUndefined(object) 
稳定 度 : 0 - FA 


如 果 object 是 undefined 则 返回 true > GIAE false 。 
var util = require('util'); 


var foo; 
util.isUndefined(5) 
// false 
util.isUndefined( foo) 
// true 
util.isUndefined(null) 
// false 


util.isObject(object) 


稳定 度 : 0 - 弃 用 


如 果 object 严格 的 是 一 个 对 象 而 不 是 一 个 函数 ， 则 返回 true > SMR 
= false ° 


var util = require('util'); 


util.isObject(5) 

// false 
util.isObject(null) 

// false 
util.isObject({}) 

// true 
util.isObject(function(){}) 

// false 


util.isFunction(object) 
稳定 度 : 0 - FA 


如 果 object 是 一 个 函数 则 返回 true > SMA false 。 
var util = require('util'); 


function Foo() {} 
var Bar = function() {}; 


util.isFunction( {}) 
// false 

util.isFunction(Foo) 
// true 

util.isFunction(Bar) 
// true 


util.isPrimitive(object) 
稳定 度 : 0 - 弃 用 


如 果 object 是 一 个 基本 值 则 返回 true > GIAE false ° 


var util = require('util'); 


util.isPrimitive(5) 

// true 
util.isPrimitive('foo') 

/7 true 
util.isPrimitive(false) 

// true 
util.isPrimitive(null) 

/7/ true 
util.isPrimitive(undefined) 

// true 
util.isPrimitive({}) 

// false 
util.isPrimitive(function() {}) 

// false 
util.isPrimitive(/‘$/) 

// Talse 
util.isPrimitive(new Date()) 

// Talse 


util.isBuffer(object) 
稳定 度 : 0 - 弃 用 


如 果 object 是 一 个 buffer 则 返回 true > SMA false 。 
var util = require('util'); 


util.isBuffer({ length: © }) 
// Talse 

util.isBuffer([]) 
/7? false 

util.isBuffer(new Buffer('hello world')) 
// true 


util.inherits(constructor, superConstructor) 


将 一 个 构造 函数 所 有 的 原型 方法 继承 到 到 另 一 个 中 。 构 造 函 数 的 原型 将 会 被 设置 为 
一 个 超 类 创建 的 新 对 象 。 


为 了 方便 起 见 ， 超 类 可 以 通过 constructor.super_ 来 访问 。 


var util = require("util"); 
var events = require("events"); 


function MyStream() { 
events.EventEmitter.call(this); 


util.inherits(MyStream, events.EventEmitter); 


MyStream.prototype.write = function(data) { 
this.emit("data", data); 


var stream = new MyStream(); 


console.log(stream instanceof events.EventEmitter); // true 
console.log(MyStream.super_ === events.EventEmitter); // true 


stream.on("data", function(data) { 
console.log('Received data: "' + data + '"'); 


}) 


stream.write("It works!"); // Received data: "It works!" 


util.deprecate(function, string) 


标记 一 个 方法 为 不 应 再 使 用 。 
var util = require('util'); 


exports.puts = util.deprecate(function() { 
for (var i = 0, len = arguments.length; i < len; ++i) { 
process.stdout.write(arguments[i] + '\n'); 


} 


}, 'util.puts: Use console.log instead'); 


默认 返回 一 个 被 运行 时 会 发 出 一 次 警告 的 ， 人 和 修改 后 的 函数 。 


如 果 --no-deprecation 被 设置 ， 那 么 这 个 函数 将 为 室 。 可 以 在 运行 时 通 
过 process.noDeprecation 布尔 值 配置 (只 有 在 模块 被 加 载 前 设置 ， 才 会 有 
效 ) 。 


如 果 --trace-deprecation 被 设置 ， 当 被 弃 用 的 AP| 第 一 次 被 使 用 时 ， 会 向 控制 
侣 打印 一 个 警告 和 堆栈 信息 。 可 以 在 运行 时 通过 process.traceDeprecation 布 
尔 值 配置 


如 果 --throw-deprecation 被 设置 ， 那 么 当 被 弃 用 的 API 被 使 用 时 ， 应 用 会 抛 出 
一 个 错误 。 可 以 在 运行 时 通过 process.throwDeprecation 布尔 值 配置 


process.throwDeprecation 的 优先 级 高 于 process.traceDeprecation ° 


util.debug(string) 
稳定 度 : 0 - 弃 用 : 使 用 console.error() 代替 。 


被 弃 用 ， console,error 的 前 身 。 


util.error([...]) 
稳定 度 : 0 - FA: 使 用 console.error() 代替 。 


RAM > console,error 的 前 身 。 


util.puts([...]) 
稳定 度 : 0 - FIA: 使 用 console.log() 代替 。 


被 弃 用 ， console.log 的 前 身 。 


util.print([...]) 
稳定 度 : 0 - FA: 使 用 console.log() 代替 。 


RAR > console.log 的 前 身 。 


util.pump(readableStream, writableStream[, callback]) 


稳定 度 : 0 - FA: 使 用 readableStream.pipe(writableStream) 代替 。 


MF Fl > stream.pipe() 的 前 身 。 


V8 


PER: 2-2 


这 个 模块 暴露 了 node.js 内 建 的 指定 版 本 的 V8 的 事件 和 接口 。 这 些 接 口 受 上 游 
(upstream) 变化 的 影响 ， 所 以 没有 被 稳定 索引 (stability index) 所 覆盖 。 


getHeapStatistics() 


返回 一 个 包含 以 下 属性 的 对 象 。 


total_heap_size: 7326976, 
total_heap_size_executable: 4194304, 
total_physical_size: 7326976, 
used_heap_size: 3476208, 

heap_size_ limit: 1535115264 





setFlagsFromString(string) 


设置 额外 的 V8 命令 行 标识 。 请 谨 懂 使 用 ; 在 虚拟 机 启动 后 改变 设 定 可 能 会 产生 不 可 
预测 的 行为 ， 包 括 程 序 衣 溃 或 数据 丢失 。 或 者 它 也 可 能 什么 都 没有 做 。 


o 


当前 node.js 可 用 的 V8 选 项 ， 在 运行 iojs --v8-options 命令 的 输出 中 显示 
一 个 非 官方 ， 社 区 维护 的 配置 列表 : https://github.com/thlorenz/vs- 
flags/blob/master/flags-0.11.md ° 


用 处 : 


// Print GC events to stdout for one minute. 

var v8 = require('v8'); 

v8.setFlagsFromString('--trace_gc'); 

setTimeout(function() { v8.setFlagsFromString('--notrace_gc'); } 
, 60e3); 


V8 


347 


执行 JavaScript 
稳定 度 : 2 - 稳定 

要 获取 这 个 模块 ， 你 可 以 通过 
var vm = require('vm'); 


JavaScript 代码 会 被 编译 且 立 刻 执行 A MIE RA HAAG 


人 


vm.runInThisContext(code[, options]) 
vm.runInThisContext() 编译 代码 ， 运 行 它 ， 然 后 返回 结果 。 运 行 中 的 代码 不 能 
访问 本 地 作用 域 ， 但 是 可 以 访问 当前 的 全 局 对 象 。 


使 用 vm.runInThisContext 和 eval 运行 相同 代码 的 例子 


var vm = require('vm'); 
var localVar = 'initial value'; 


var vmResult = vm.runInThisContext('localVar = "vm";'); 
console.log('vmResult: ', vmResult); 
console.log('localVar: ', localVar); 


var evalResult = eval('localVar = "eval";'); 
console.log('evalResult: ', evalResult); 
console.log('localVar: ', localVar); 


// vwmResult: ‘vm', localVar: ‘initial value 
// evalResult: 'eval', localVar: 'eval' 


vm.runInThisContext 不 能 访问 本 地 作用 域 ， 所 以 localvar 没有 改 
变 。 eval 可 以 访问 本 地 作用 域 ， 所 以 localVar 改变 了 。 


这 种 情况 下 ， vm.runInThisContext ees. eval 调用 ， 
像 (0,eval)('code') 。 但 是 ， 它 还 有 以 下 这 些 额 外 的 选 


e filename: 允许 你 控制 提供 在 堆栈 追踪 信息 中 的 文件 名 。 

e displayErrors: 是 否 在 抛 出 异常 前 向 stderr 打印 任何 的 错误 ， 并 且 造 成 错误 
的 行 会 被 高 亮 。 会 捕获 编译 代码 时 的 语法 错误 和 编译 完 的 代码 运行 时 抛 出 的 异 
常 。 默 认为 true 。 

e timeout: 在 关闭 之 前 ， 允 许 代 码 执行 的 时 间 (毫秒 ) 。 如 果 超 时 ， 一 个 错误 被 
会 抛 出 。 


vm.createContext([sandbox]) 


如 果 指 定 了 一 个 sandbox 对 象 ， 则 将 sandbox“ 上 下 文化 "， 这 样 它 才 可 以 

被 vm.runInContext 或 script.runInContext 使 用 。 在 脚本 内 

部 ， sandbox 将 会 是 全 局 对 象 ， 保 留 了 它 自己 所 有 的 属性 ， 并 且 包 含 内 建 对 象 和 
标准 全 局 对 象 的 所 有 了 肠 数 。 在 由 vm 模块 运行 的 脚本 之 外 的 地 方 ， sandbox 将 不 
会 被 改变 。 


如 果 没 有 指定 sandbox 对 象 ， 将 会 返回 一 个 你 可 以 使 用 的 新 的 ， 无 内 容 
的 sandbox 对 象 。 


这 个 函数 在 创建 被 用 来 运行 多 个 脚本 的 沙 箱 时 十 分 有 有用， 例如， 如 果 你 正在 模拟 一 
个 web 浏 览 器 ， 则 可 以 创建 一 个 代表 了 window 全 局 对 象 的 沙 箱 ， 然 后 在 沙 箱 内 运 
行 所 有 的 <script> 标签 。 


vm.isContext(sandbox) 


返回 一 个 沙 箱 是 否 已 经 通过 调用 vm.createContext 上 下 文化 。 


vm.runInContext(code, contextifiedSandbox[, options]) 


vm.runInContext 编译 代码 ， 然 后 将 其 在 contextifiedSandbox 中 和 运行， 然后 
返回 结果 。 和 运行 的 代码 不 能 访问 本 地 作用 域 。 contextifiedSandbox 必须 通 
过 vm.createContext 上 下 文化 ; 它 被 用 来 当做 代码 的 全 局 对 象 。 


vm.runInContext 的 选项 和 vm.runInThisContext 相同 。 


例子 : 编译 并 执行 不 同 的 脚本 ， 在 同一 个 已 存在 的 上 下 文中 。 


var util = require('util'); 
var vm = require('vm'); 
var sandbox 


{ globalVar: 1 }; 
vm. createContext (sandbox); 


for (var i= ©; i < 10; +41) { 
} 


vm. runInContext('globalVar *= 2;', sandbox); 
globalVar: 


console. log(util.inspect (sandbox) ); 
7 A o 1024 


} 


NS o 


是 将 它们 放 在 另 一 个 单独 的 进程 中 为 好 。 


注意 ， 运 行 不 受信 任 的 代码 是 一 个 十 分 环 手 的 工作 ， 需 要 十 分 /'] 
vm.runInContext 是 十 分 有 用 的 ， 但 是 为 了 安全 的 运行 不 受 1 


x 


ZAZIE AY RAG > 36 
vm.runInNewContext(code[, sandbox][, options]) 
vm.runInNewContext 编译 代码 ， 接 着 ， 如 果 传 递 了 sandbox 则 上 下 文 
化 sandbox ， 如 果 没 有 就 创建 一 个 新 的 已 上 下 文化 的 沙 箱 ， 然 后 将 沙 箱 作为 全 局 
对 象 运行 代码 并 返回 结果 。 
vm.runInNewContext 的 选项 和 vm.runInThisContext 相同 。 

例子 : 编译 并 执行 
些 全 局 变量 包含 在 沙 箱 中 。 


一 个 自 增 一 个 全 局 变量 然后 设置 一 个 新 的 全 局 变量 的 代码 。 这 


var util 
var vm 


require('util'); 
require('vm'); 


var sandbox 


= 
animal: 'cat' 
count: 2 
}; 
vm.runInNewContext('count += 1; name = "kitty"', sandbox); 
console. log(util.inspect (sandbox) ); 
// { animal: 'cat', count: 3, name: 
注意 ， 
ny o 
Alb 9 


Akane 
运行 不 受信 任 的 代码 是 一 个 十 分 棘手 的 工作 ， 需 要 十 分 
vm.runInNewContext 是 十 分 有 用 的 ， 但 是 为 了 安全 

将 它们 放 在 另 


~ THRE 
一 个 单独 的 进程 中 为 好 。 
vm.runinDebugContext(code) 


言 任 的 代 
vm.runInDebugContext 编译 代码 ， 然 后 
用 途 是 访问 V8 调 试 对 象 


var Debug 
me); }); 


们 在 V8 调 试 上 下 文中 执行 。 主 要 的 
vm. runInDebugContext('Debug'); 


况 就 发 生 改 变 (或 被 移 除 ) 
调试 对 象 也 可 以 


Debug.scripts().forEach(function(script) { console.log(script.na 
主意 ， 调 试 上 下 文 和 对 得 与 V8 的 调试 实现 联系 紧密 ， 它 们 可 能 在 没有 事先 提醒 的 


--expose_debug_as= switch XWA Š ° 
Class: Script 


一 个 包含 预 编译 代码 ， 然 后 将 


它们 运行 在 和 中 的 类 
new vm.Script(code, options) 


创建 一 个 编译 代码 但 不 执行 它 的 新 Script 类 。 也 就 是 说 ， 一 个 创建 好 

的 vm.Script 对 象 代 表 了 它 的 编译 完毕 的 代码 。 这 个 脚本 已 经 通过 下 文 的 方法 在 
晚 些 时 候 被 调用 多 次 。 返 回 的 脚本 没有 被 绑 定 在 任何 的 全 局 对 象 上 。 它 可 以 在 每 次 
运行 前 被 缚 定 ， 所 以 只 在 那 次 运行 时 有 效 。 


options 可 以 有 以 下 属性 : 


e filename: 允许 你 控制 提供 在 堆栈 追踪 信息 中 的 文件 名 。 

e displayErrors: 是 否 在 抛 出 异常 前 向 stderr 打印 任何 的 错误 ， 并 且 造 成 错误 
的 行 会 被 高 亮 。 会 捕获 编译 代码 时 的 语法 错误 和 运行 时 由 脚本 的 方法 的 配置 所 
控制 的 代码 抛 出 的 错误 。 


script.runlnThisContext([options]) 


与 vm,runInThisContext 相似 ， 但 是 是 一 个 预 编 译 的 Script 对 象 的 方 
法 。 script.runInThisContext 运行 脚本 被 编译 完毕 的 代码 ， 然 后 返回 结果 。 运 
行 中 的 代码 不 能 访问 本 地 作用 域 ， 但 是 可 以 访问 当前 的 全 局 对 象 。 


一 个 使 用 script.runInThisContext 来 编译 一 次 代码 ， 然 后 运行 多 次 的 例子 
var vm = require('vm'); 
global.globalVar = 0; 


var script = new vm.Script('globalVar += 1', { filename: 'myfile 


vm' 3); 


for (Vay 1 = 0; i< 1000; +41) A 
script.runInThisContext(); 


console.log(globalVar ); 


// 1000 


options 可 以 有 以 下 属性 : 


e displayErrors: 是 否 在 抛 出 异常 前 向 stderr 打印 任何 的 错误 ， 并 且 造 成 错误 
的 行 会 被 高 亮 。 只 会 应 用 于 运行 中 代码 的 执行 错误 ; ; 创建 一 个 有 语 法 错误 
的 Script 实例 是 不 可 能 的 ， 因 为 构造 函数 会 抛 出 出 常 


e timeout: 在 关闭 之 前 ， 允 许 代 码 执 行 的 时 间 (BAY) 。 如 果 超 时 ， 一 个 错误 被 
会 抛 出 。 


script.runInContext(contextifiedSandbox[, options]) 


与 yvm.runInContext 相似 ， PER Script o 
法 。 script.runInContext 运行 脚本 被 编译 完毕 的 代码 ， 然 后 返回 结果 。 运 行 中 
的 代码 不 能 访问 本 地 作用 域 。 


script.runInContext 的 选项 和 script.runInThisContext 相同 。 
例子 : 编译 一 段 自 增 一 个 全 局 对 象 并 且 创 建 一 个 全 局 对 象 的 代码 ， 然 后 执行 多 
次 ， 这 些 全 局 对 象 包含 在 沙 箱 中 。 


var util = require('util'); 
var vm = require('vm'); 


var sandbox = { 
animal: 'cat', 
count: 2 


Pe 


var context = new vm.createContext(sandbox); 
var script = new vm.Script('count += 1; name = "kitty"'); 


fOr (Var =O; a= 10) +71) 4 


script. runInContext (context); 


console. log(util.inspect (sandbox) ); 


1 


/7 { anamal: am count: 12, name: Key 


注意 ， 运 行 不 受信 任 的 代码 是 一 个 十 分 棘手 的 工作 ， 需 要 十 分 
心 。 script.runInContext 是 十 分 有 用 的 ， 但 是 为 了 安全 = 了 不 受信 任 的 代 
码 ， 还 是 将 它们 放 在 另 一 个 单独 的 进程 中 为 好 。 


script.runinNewContext([sandbox][, options]) 


与 vm.runInNewContext 相似 ， 但 是 是 一 个 预 编译 的 Script 对 象 的 方法 。 如 果 
传递 了 sandbox , script.runInNewContext 将 上 下 文化 sandbox ， 如 果 a 
就 创建 一 个 新 的 已 上 下 文化 的 沙 箱 ， 然 后 将 沙 箱 作 为 全 局 对 象 运行 代码 并 返 

运行 中 的 代码 不 能 访问 本 地 作用 域 。 


script.runInNewContext 的 选项 和 script.runInThisContext 相同 。 


例子 : 编译 一 段 设置 一 个 全 局 对 象 的 代码 ， 然 后 在 不 同 的 上 下 文中 多 次 执行 它 。 
这 些 全 局 对 象 包含 在 沙 箱 中 。 


var util = require('util'); 
var vm = require('vm'); 


var sandboxes = [{}, {}, {}]; 
var script = new vm.Script('globalVar = "set"'); 


sandboxes.forEach(function (sandbox) { 
script .runInNewContext (sandbox); 


}); 
console.log(util.inspect(sandboxes)); 
// I4 globalVar: set t, { globalVar: tset! }, 4 globalVar: “se 
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注意 ， 运 行 不 受信 任 的 代码 是 一 个 十 分 棘手 的 工作 ， 需 要 十 分 
心 。 script.runInNewContext 是 十 分 有 用 的 ， 但 是 为 了 不 受信 任 的 
代码 ， 还 是 将 它们 放 在 另 一 个 单独 的 进程 中 为 好 。 


Zlib 


稳定 度 : 2 -稳定 
要 获取 这 个 模块 ， 你 可 以 通过 : 


var zlib = require('zlib'); 


它 提 供 了 Gzip/Gunzip ， Deflate/Inflate 和 DeflateRaw/InflateRaw 类 的 
绑 定 。 每 个 类 都 有 相同 的 选项 ， 并 且 都 是 可 读 / 可 写 流 。 


例子 


可 以 通过 将 一 个 fs.ReadStream 的 数据 导入 一 个 zlib 流 ， 然 后 导入 一 
个 fs.WriteStream ， 来 压缩 或 解压 缩 一 个 文件 。 


var gzip = zlib.createGzip(); 

Vale Ses regure rsa) 

var inp = fs.createReadStream('input.txt'); 

var out = fs.createWriteStream('input.txt.gz'); 


inp.pipe(gzip).pipe(out); 


mi 
my 
ws 
ay 

Dal 
rt 
ss 
ee 
a 


WS RAK TULA-APRERREH 


var input = nce cha ncneveie eects Gace E ane ein aceon ee a 
zlib.deflate(input, function(err, buffer) { 


if (!err) { 
console. log(buffer.toString( 'base64')); 
} 
}); 


var buffer = new Buffer('eJZTOyMAAGTvBe8=', 'base64'); 
zlib.unzip(buffer, function(err, buffer) { 


if (!err) { 
console. log(buffer.toString()); 
} 
}); 


如 果 要 在 HTTP 客 户 端 或 服务 器 上 使 用 这 个 模块 ， 在 请 求 时 需要 带 上 accept- 
encoding 头 ， 在 响应 时 需要 带 上 content-encoding 头 。 


注意 ， 这 些 例子 都 只 是 非常 简单 的 展示 了 一 些 基 本 的 概念 。 zlib 编码 的 开销 是 非 
常 兄 贵 的 ， 并 且 结果 需要 被 缓存 。 更 多 关于 速度 /内 存 /压缩 的 权衡 ， 请 参阅 下 文 
的 内 存 使 用 调 优 。 


// client request example 


var zlib require('zlib'); 
var http = require('http'); 
var fs = require('fs'); 


var request = http.get({ host: 'izs.me', 


path: 27", 
port: 80, 
headers: { 'accept-encoding': 'gzip, def 


late" } }); 
request .on('response', function(response) { 
var output = fs.createWriteStream('izs.me_index.html1'); 


switch (response.headers['content-encoding']) { 
// or, just use zlib.createUnzip() to handle both cases 
case 'gzip': 
response. pipe(zlib.createGunzip()).pipe(output); 
break; 
case 'deflate': 


response.pipe(zlib.createInflate()).pipe(output); 


break; 
default: 
response.pipe(output); 
break; 
} 
}); 


// server example 

// Running a gzip operation on every request is quite expensive. 
// It would be much more efficient to cache the compressed buffe 
r. 


var zlib = require('zlib'); 
var http = require('http'); 
var fs = require('fs'); 
http.createServer(function(request, response) { 
var raw = fs.createReadStream('index.html'); 
var acceptEncoding = request.headers['accept-encoding']; 
if (!acceptEncoding) { 
acceptEncoding = ''; 


// Note: this is not a conformant accept-encoding parser. 
// See http://www.w3.0rg/Protocols/rfc2616/rfc2616-sec14.html# 
seci4.3 
if (acceptEncoding.match(/\bdeflate\b/)) { 
response.writeHead(200, { 'content-encoding': 'deflate' }); 
raw.pipe(zlib.createDeflate()).pipe(response) ; 
} else if (acceptEncoding.match(/\bgzip\b/)) { 


response.writeHead(200, { 'content-encoding': 'gzip' }); 
raw.pipe(zlib.createGzip()).pipe(response) ; 
} else { 


response.writeHead(200, {}); 
raw.pipe(response); 
} 
}).1isten(1337); 


zlib.createGzip([options]) 


根据 一 个 options ， 返 回 一 个 新 的 Gzip WH ° 


zlib.createGunzip([options]) 


根据 一 个 options ， 返 回 一 个 新 的 Gunzip 对 象 。 


zlib.createDeflate([options]) 


根据 一 个 options ， 返 回 一 个 新 的 Deflate 对 象 。 


zlib.createlnflate([options]) 


根据 一 个 options ， 返 回 一 个 新 的 Inflate 对 象 。 


zlib.createDeflateRaw([options]) 


根据 一 个 options ， 返 回 一 个 新 的 DeflateRaw WH 


zlib.createlnflateRaw([options]) 


根据 一 个 options ， 返 回 一 个 新 的 InflateRaw WF 


zlib.createUnzip([options]) 


根据 一 个 options ， 返 回 一 个 新 的 Unzip 对 象 。 


Class: zlib.Zlib 

这 个 类 未 被 zlib 模块 暴露 。 它 之 所 以 会 出 现在 这 里 ， 是 因为 它 
是 compressor/decompressor 类 的 基 类 。 
zlib.flush([kind], callback) 

kind 软 认 为 zlib.Z_FULL_FLUSH ° 


冲刷 等 待 中 的 数据 。 不 要 轻率 地 调用 这 个 方法 ， 过 早 的 冲刷 会 给 压缩 算法 带 来 消极 


影响 。 


zlib.params(level, strategy, callback) 


动态 地 更 新 压缩 等 级 和 压缩 策略 。 只 适用 于 deflate 算法 。 


zlib.reset() 

将 compressor/decompressor 重 置 为 默认 值 。 只 使 用 
于 inflate 和 deflate 算法 。 

Class: zlib.Gzip 


使 用 gzip 压缩 数据 。 


Class: zlib.Gunzip 


解压 一 个 gzip 流 。 


Class: zlib.Deflate 


使 用 deflate 压缩 数据 。 


Class: zlib.Inflate 


解压 一 个 deflate ii 


Class: zlib.DeflateRaw 


使 用 deflate 压缩 数据 ， 不 添加 zlib 头 。 


Class: zlib.InflateRaw 


解压 一 个 原始 deflate 流 。 


Class: zlib.Unzip 


通过 自动 探测 头 信 息 ， 解 压 Gzip 或 Deflate 压缩 流 


便捷 方法 


所 有 的 方法 接受 一 个 字符 串 或 一 个 buffer 作为 第 一 个 参数 ， 并 且 第 二 个 参数 是 一 
个 可 选 的 zlib 类 的 配置 ， 并 且 会 以 callback(error, result) 的 形式 执行 提 
供 的 回调 函数 。 


每 一 个 方法 都 有 一 个 同步 版 本 ， 除 去 回调 函数 ， 它 们 接受 相同 的 参数 。 
zlib.deflate(buf[, options], callback) 


zlib.deflateSync(buf[, options]) 


使 用 Deflate 压缩 一 个 字符 串 。 
zlib.deflateRaw(buf[, options], callback) 


zlib.deflateRawSync(buf[, options]) 


使 用 DeflateRaw 压缩 一 个 字符 串 。 
zlib.gzip(buf[, options], callback) 
zlib.gzipSync(buf[, options]) 

使 用 Gzip 压缩 一 个 字符 串 。 
zlib.gunzip(buf[, options], callback) 


zlib.gunzipSync(buf[, options]) 


使 用 Gunzip 压缩 一 个 字符 串 。 
zlib.inflate(buf[, options], callback) 


zlib.inflateSync(buf[, options]) 


使 用 Inflate 压缩 一 个 字符 串 。 
zlib.inflateRaw(buf[, options], callback) 


zlib.inflateRawSync(buf[, options]) 


使 用 InflateRaw 压缩 一 个 字符 串 。 


zlib.unzip(buf[, options], callback) 


zlib.unzipSync(buf[, options]) 


a 


使 用 Unzip 压缩 一 个 字符 串 。 


Options 
每 一 个 类 都 接受 一 个 options 对 象 。 所 有 的 options 对 象 都 是 可 选 的 。 
注意 一 些 选 项 只 与 压缩 相关 ， 会 被 解压 缩 类 忽略 : 


e flush (默认 : zlib.Z_NO_FLUSH ) 

e chunkSize (默认 : 16*1024 ) 

e windowBits 

e level ( 仅 用 于 压缩 ) 

e memLevel ( 仅 用 于 压缩 ) 

e strategy ( 仅 用 于 压缩 ) 

e dictionary ( 仅 用 于 deflate/inflate > RUX ÈH X) 


参 
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阅 http://zlib.net/manual.html#Advanced 中 deflateInit2 和 inflateIn 
it2 的 描述 来 获取 更 多 信息 。 


内 存 使 用 调 优 
KÁ zlib/zconf.h ， 将 其 修改 为 node.js 的 用 法 : 


默认 的 内 存 要 求 (FF) 为 : 


(1 << (windowBits+2)) + (1 << (memLevel+9) ) 


换言之 : windowBits=15 的 128K 加 上 menLevel = 8 (默认 值 ) 的 128K 加 上 
其 他 小 对 象 的 一 些 字 节 。 


例子 ， 如 果 你 想 要 将 默认 内 存 需 求 从 256K 减 少 至 128K， 将 选项 设置 为 : 


{ windowBits: 14, memLevel: 7 } 


inflate 的 内 存 需求 (FP) 为 : 


1 << windowBits 


换言之 : windowBits=15 (RUA) 的 32K 加 上 其 他 小 对 象 的 一 些 字 节 。 
这 是 内 部 输出 缓冲 外 的 chunkSize 大 小 ， 黑 认为 16K ° 


Zlib 压缩 的 速度 动态 得 受 设置 的 压缩 等 级 的 影响 。 高 的 等 级 会 带 来 更 好 地 压缩 效 
果 ， 但 是 花费 的 时 间 更 长 。 低 的 等 级 会 带 来 更 少 的 压缩 效果 ， 但 是 更 快 。 


通常 ， 更 高 的 内 存 使 用 选项 意味 着 node.js 会 调用 zlib 因为 在 一 次 


单独 的 写 操作 中 它 可 以 处 理 更 多 的 数据 。 所 以 ， 这 是 影响 速度 和 内 存 占 用 的 另 一 个 
因素 。 
常量 


所 有 在 zlib.h 中 定义 的 常量 ， 都 也 被 定义 在 了 require('zlib') 中 。 大 多 数 操 
作 中 ， 你 都 将 不 会 用 到 它们 。 它 们 出 现在 这 里 只 是 为 了 让 你 对 它们 的 存在 不 套 感到 
惊讶 。 该 章节 几乎 完全 来 自 zlib 文件 。 更 多 详情 请 参 
阅 http://zlib.net/manual.html#Constants ° 


允许 的 冲刷 值 


zlib.Z_NO_FLUSH 
zlib.Z_PARTIAL_FLUSH 
zlib.Z_SYNC_FLUSH 
zlib.Z_FULL_FLUSH 
zlib.Z_FINISH 
zlib.Z_ BLOCK 
zlib.Z_TREES 


compression/decompression HA JA Ah o MIERKE > EMR RARE 
是 正常 的 事件 : 


zlib.Z_OK 

zlib.Z STREAM_END 
zZlib.Z NEED DICT 
zlib.Z ERRNO 

zlib.Z STREAM_ERROR 
zlib.Z _DATA_ERROR 
zlib.Z MEM_ERROR 
zlib.Z _BUF_ERROR 
Z1lib.Z_VERSION_ERROR 


压缩 等 级 : 


zlib.Z_NO_COMPRESSION 
zlib.Z BEST _SPEED 
zlib.Z BEST COMPRESSION 
Z1lib.Z DEFAULT_COMPRESSION 


压缩 策略 : 


zlib.Z FILTERED 

Zlib.Z HUFFMAN_ONLY 
zlib.Z_RLE 

zlib.Z FIXED 

Zlib.Z DEFAULT_STRATEGY 


data_type 域 的 可 能 值 : 


zlib.Z BINARY 
zlib.Z_TEXT 
zlib.Z_ASCII 
zlib.Z_UNKNOWN 


deflate 压缩 方法 (当前 版 本 只 支持 这 一 个 ) 


zlib.Z DEFLATED 


用 于 初始 化 zalloc ， zfree ， opaque 


zlib.Z_ NULL 


